diff --git a/content/.metadata.json b/content/.metadata.json index 08ce4e0d2..cd6262aba 100644 --- a/content/.metadata.json +++ b/content/.metadata.json @@ -1,64 +1,22 @@ { "metadata": { "version": "1.0", - "fetch_date": "2026-04-08T11:44:17.716242Z" + "fetch_date": "2026-04-09T03:41:21.877835Z" }, "items": [ { "url": "https://platform.claude.com/docs/en/intro", "status": "success", "path": "en/intro.md", - "sha256": "f270042814a8c4a7c374311a10f3027d6cc319cd4384586c163c1a3626a46fdd", - "size": 3361 + "sha256": "bc97e117ec735d4acefa973cbc98be587d08271cc8aca6034c48435f692c9d6f", + "size": 3893 }, { "url": "https://platform.claude.com/docs/en/get-started", "status": "success", "path": "en/get-started.md", - "sha256": "daa19686eb1690fc82967c1dd3aad4c497c71d3178ab580383ae1f71d5be4b49", - "size": 11143 - }, - { - "url": "https://platform.claude.com/docs/en/about-claude/models/overview", - "status": "success", - "path": "en/about-claude/models/overview.md", - "sha256": "db4358115c019eb7eb23012ec34de4ba0683159aa25a96b626f8f0e5d565c560", - "size": 10037 - }, - { - "url": "https://platform.claude.com/docs/en/about-claude/models/choosing-a-model", - "status": "success", - "path": "en/about-claude/models/choosing-a-model.md", - "sha256": "96c928e062ca62bc43029b5b68166cb7c0e2e46a22f25ff3de68cc1c722813d2", - "size": 4348 - }, - { - "url": "https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-6", - "status": "success", - "path": "en/about-claude/models/whats-new-claude-4-6.md", - "sha256": "7a98cfa1cc0875b8983e8811a50d94d61beee0a22ff217d9b70bbca5b8d8b555", - "size": 9804 - }, - { - "url": "https://platform.claude.com/docs/en/about-claude/models/migration-guide", - "status": "success", - "path": "en/about-claude/models/migration-guide.md", - "sha256": "c0ace79841921633737d6aeae292bc44a6decaecff19b49241aab904b8c10705", - "size": 45161 - }, - { - "url": "https://platform.claude.com/docs/en/about-claude/model-deprecations", - "status": "success", - "path": "en/about-claude/model-deprecations.md", - "sha256": "cebc827b87f099d1c5f132fb76e95cc707451139199787123018263346d1c403", - "size": 9176 - }, - { - "url": "https://platform.claude.com/docs/en/about-claude/pricing", - "status": "success", - "path": "en/about-claude/pricing.md", - "sha256": "acdade6d72307ed5f370d8cc01b8cda4c21ec38146e069b687cc5d920ab6e89e", - "size": 20885 + "sha256": "c173b9740127d9005f770160bfcc06afe490f5933b3a2b4b8c1d9532f5bb2676", + "size": 13809 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/overview", @@ -71,92 +29,85 @@ "url": "https://platform.claude.com/docs/en/build-with-claude/working-with-messages", "status": "success", "path": "en/build-with-claude/working-with-messages.md", - "sha256": "1b0735cd3122c463926fc8898f9c3836a1d5459a7de79c9d0f603c1886286ca4", - "size": 32314 + "sha256": "b9e9b2d551201e2e519bd4e821397a22d15f27268698b909194ccde75ed68dc2", + "size": 34431 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons", "status": "success", "path": "en/build-with-claude/handling-stop-reasons.md", - "sha256": "e8c9fb62f2c4877fe6e3c6c580c694833959e0d89e9269aacd839eabd2cfca83", - "size": 24054 - }, - { - "url": "https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices", - "status": "success", - "path": "en/build-with-claude/prompt-engineering/claude-prompting-best-practices.md", - "sha256": "5387b42af4e10ee84c29d988fad36e4d8623f5c40eec34a682b8758c1f7daf90", - "size": 46827 + "sha256": "d8102d8b7c9cba1887f0a7b739e2e5887c23e051ccb88dd1be9ed178c635a2a4", + "size": 24559 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/extended-thinking", "status": "success", "path": "en/build-with-claude/extended-thinking.md", - "sha256": "675f93e33dfaf7523de39df3f84b94894418dc37881335e9d834ea3cabdb3b92", - "size": 134777 + "sha256": "b75580d6218a6afa608d25ae431cf7e26dbf1dedca39c5555cc08a88aadcd06c", + "size": 141629 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking", "status": "success", "path": "en/build-with-claude/adaptive-thinking.md", - "sha256": "1090bb59f5f0beb2ec817338a91f55880952c4b0c0942c5c4ce0399ce5ba6818", - "size": 33409 + "sha256": "fa1242fa01a7fac4fbec229751ef734d5d2d4ea576f0dfd7d0497f2a0949a1be", + "size": 34320 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/effort", "status": "success", "path": "en/build-with-claude/effort.md", - "sha256": "277a214b03c522810c58850a16f1c706941b58c012bb368bd3e0544beb2ad6f1", - "size": 12940 + "sha256": "2257478112eac890dacc5b48de8491cbcf2e7a7a8dad1ab3748c39d2bfc6346b", + "size": 13218 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/fast-mode", "status": "success", "path": "en/build-with-claude/fast-mode.md", - "sha256": "df52ecbb0b0ffdcc743c33ebaf808f9d9f9ae4c6ad736a7c834781f68e4ea405", - "size": 23394 + "sha256": "cc2363876a07e1776314435e8db4d9b1cb3fbe6648f3172f665a1d4c1be9c74e", + "size": 25028 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/structured-outputs", "status": "success", "path": "en/build-with-claude/structured-outputs.md", - "sha256": "c41d099e71a06cd378c225d088f9c275fceec3a8535e32bd45e48662a9b9fc5e", - "size": 86086 + "sha256": "6645a33caa9a4a27d4c8789be2bddd700ce85f5546ea1001958b5c476a26a65c", + "size": 91474 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/citations", "status": "success", "path": "en/build-with-claude/citations.md", - "sha256": "6f2d7d294f11227f419e250912c750b83fd3ce62714b06883adc1bfb244d94ac", - "size": 20757 + "sha256": "6a34f028adf565d5ef7e48a26da5a1d317f1db2dd20b46dfd8b9d5805c56709b", + "size": 21694 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/streaming", "status": "success", "path": "en/build-with-claude/streaming.md", - "sha256": "8d11b7e81e4d97c525395f4082b87e80e44a01934b8729b82981467174de06de", - "size": 51399 + "sha256": "9151ecbbeeb955b38f90087f427ee85627bb8c72ea7ba72f0cae66d87c0b36a6", + "size": 53335 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/batch-processing", "status": "success", "path": "en/build-with-claude/batch-processing.md", - "sha256": "d7e9f58bcd5e7eec6054017e7ece4d6e184ef4ff69217f0f025ea75566e7f6e0", - "size": 69148 + "sha256": "4dc409ece243e46706d06b6cb167735c6ef3236490300a6041b3497c4a3665ba", + "size": 73096 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/pdf-support", + "url": "https://platform.claude.com/docs/en/build-with-claude/search-results", "status": "success", - "path": "en/build-with-claude/pdf-support.md", - "sha256": "0321058144ebb3999b13ddb92e504ff2831d9e03533388af2487355d28a7ee8d", - "size": 35078 + "path": "en/build-with-claude/search-results.md", + "sha256": "78a8c66b72b812cc86ae40bfed952d16e5e488596e56349b68bdc153f213d9aa", + "size": 51825 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/search-results", + "url": "https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals", "status": "success", - "path": "en/build-with-claude/search-results.md", - "sha256": "f9a9f5839a09471c479579085303e8ef54d0f9b2f6508c8ce3d5366a1012b8a9", - "size": 50640 + "path": "en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals.md", + "sha256": "7e435c6d28bf7b3af668ca0052394f44b46ae0d15c075c5b11dba98c07545216", + "size": 10245 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/multilingual-support", @@ -172,19 +123,12 @@ "sha256": "1e94a92de3d5332b1bebf9de4f9b2c250fc216a3b535038081a42231e831a3d0", "size": 16342 }, - { - "url": "https://platform.claude.com/docs/en/build-with-claude/vision", - "status": "success", - "path": "en/build-with-claude/vision.md", - "sha256": "1d03f0874e98554414d95f0060102f89d19582c29f78243517cd576e787832cf", - "size": 48774 - }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview", "status": "success", "path": "en/agents-and-tools/tool-use/overview.md", - "sha256": "9cfae879402b619a5af59b98a76b6f47c8b3d797891c0c916a9d6fd5bc2390a0", - "size": 8292 + "sha256": "471c863cda26c756b77c7f8032cf753fe6597d2ad51bee2ebc01644800e3c65f", + "size": 8551 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works", @@ -193,159 +137,75 @@ "sha256": "fdcca0c84400350cad257fd4be100f18d94e68ce0f78392f73637064209923b7", "size": 8562 }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent", - "status": "success", - "path": "en/agents-and-tools/tool-use/build-a-tool-using-agent.md", - "sha256": "677f70f339b94a63e997c6d2ca271a95647ada90de17c8df94bc5becc77b177e", - "size": 48814 - }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools", - "status": "success", - "path": "en/agents-and-tools/tool-use/define-tools.md", - "sha256": "a4455dfae407bb148caaf5290f21a916be77185e1b654c94b0042e95633822c2", - "size": 23515 - }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls", - "status": "success", - "path": "en/agents-and-tools/tool-use/handle-tool-calls.md", - "sha256": "a979d8d08af1e9acff04b54f2fa7f5b6de2012a391c52f9ab53b1157f336bd9b", - "size": 9254 - }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use", - "status": "success", - "path": "en/agents-and-tools/tool-use/parallel-tool-use.md", - "sha256": "b39229b20635003c3b809fa91103f5ef1e196ac8faaa6c24cd0f2ae9afd36b8c", - "size": 30275 - }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner", - "status": "success", - "path": "en/agents-and-tools/tool-use/tool-runner.md", - "sha256": "6778e207434743fa1b896d7581501c6389f6a617119326ada99eeb5cc9f561e1", - "size": 26686 - }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use", - "status": "success", - "path": "en/agents-and-tools/tool-use/strict-tool-use.md", - "sha256": "5562fb8ea40a1dde2afcc748abee540ce27ffd1edbf00bac77069446737a50dd", - "size": 33859 - }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching", - "status": "success", - "path": "en/agents-and-tools/tool-use/tool-use-with-prompt-caching.md", - "sha256": "a19f41d804915b99e89864c6b7f142a963009a0cb71558f621d1628e47f530bc", - "size": 4759 - }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools", - "status": "success", - "path": "en/agents-and-tools/tool-use/server-tools.md", - "sha256": "7652d270450e6ef17736ee1c40167c0b3306810fa3eae4afab99e90c426280d6", - "size": 15958 - }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use", - "status": "success", - "path": "en/agents-and-tools/tool-use/troubleshooting-tool-use.md", - "sha256": "e25c7591a5b27a96fab7d14b22f76ffe27e0a1bbfdb45bc2302c8d0251cb8fc2", - "size": 4247 - }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", - "status": "success", - "path": "en/agents-and-tools/tool-use/tool-reference.md", - "sha256": "be6fe8fb639afde02303365119ff2327c46edd378b7c6c6bd821443474603820", - "size": 7145 - }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool", "status": "success", "path": "en/agents-and-tools/tool-use/web-search-tool.md", - "sha256": "05074f62a90c5d568241b3435feb5bb9f6ba5d7cfdda1b85aa31acee05e2c8e6", - "size": 20393 + "sha256": "f844f0fb43d570987b715115e6c8b472f67128174844fd7b9a610ce0ed70da73", + "size": 20936 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool", "status": "success", "path": "en/agents-and-tools/tool-use/web-fetch-tool.md", - "sha256": "f0622b4302ab52259d49ef938932038c7d84671b070a3a3d1c1976971a85e799", - "size": 23297 + "sha256": "4fb89733a07e946d8a2b39e3806cd30b524bb26878281c7c53fb24cbec6bbe7a", + "size": 23874 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "status": "success", "path": "en/agents-and-tools/tool-use/code-execution-tool.md", - "sha256": "d4856566311bc55bfe173b4fcec88846c854805b771cfc588c004ec7588800e9", - "size": 52124 + "sha256": "8d0dfbe0ae0185b2d0a6b75560d48bde836ff34aeaec8f2d5bbf206b484b09a6", + "size": 54618 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool", "status": "success", "path": "en/agents-and-tools/tool-use/memory-tool.md", - "sha256": "fa6652d55aca22cce187720e41493a194806eaf69f9566bbf64c848190c9229d", - "size": 22905 + "sha256": "358d94ffad5fcc97f65c3ec71706892a7a84f25870d3ce0c60845bb31d87fcb6", + "size": 23610 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool", "status": "success", "path": "en/agents-and-tools/tool-use/bash-tool.md", - "sha256": "c6c28eb2b4f1c494b504d349164a062a425fe187555b74e6d63f93939dca7d56", - "size": 13968 + "sha256": "c163b24480a6cad553a51a4bf6ac2f07d433c0d4012724a74992da170fc8e88c", + "size": 14189 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool", "status": "success", "path": "en/agents-and-tools/tool-use/computer-use-tool.md", - "sha256": "8d85c813bf43cd1d8bcb17a3eb02457f324e38be9ab815e9cb195874eb5361e5", - "size": 40726 + "sha256": "cb320e68dbdb0a4076456c8e070a0c67a78d443141effab78b79132d9fa7eb87", + "size": 41168 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool", "status": "success", "path": "en/agents-and-tools/tool-use/text-editor-tool.md", - "sha256": "d3cac90d00891dd7d15b46d1928ebd3ad775ea030f80341202340cf916ffbc73", - "size": 40797 - }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/manage-tool-context", - "status": "success", - "path": "en/agents-and-tools/tool-use/manage-tool-context.md", - "sha256": "ffb2d4526ad0516145446dec17caded0887a334ffe58ef540bbf58b0e2894917", - "size": 4606 - }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-combinations", - "status": "success", - "path": "en/agents-and-tools/tool-use/tool-combinations.md", - "sha256": "9ef3cff9d6bb2d577f71f5b8da2a5bc25869c089db89f896282ebbb19eebd3c0", - "size": 4874 + "sha256": "d9db7b0aef16767d0e6d39d8512d549dd36dce32b4b1442a96df130da310a6d3", + "size": 44358 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool", "status": "success", "path": "en/agents-and-tools/tool-use/tool-search-tool.md", - "sha256": "5a0377fe589a543ba20760a4f0703a310b0c5a5373a957a8e03d89be93af3240", - "size": 29664 + "sha256": "4f5c5b8446026ebd4aa6870a9cbcb3e2d815369b81685b932053f8b7bee0f4a2", + "size": 30516 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling", "status": "success", "path": "en/agents-and-tools/tool-use/programmatic-tool-calling.md", - "sha256": "16ac417efda0dba9b15528a5e86524504d01ec5ad9cb56196e5ecce2e175d931", - "size": 45454 + "sha256": "bb3dd7c985f8c8e33ebc93e3c4b947a19cceb2821532811692657e1bd76cfa2e", + "size": 47109 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming", "status": "success", "path": "en/agents-and-tools/tool-use/fine-grained-tool-streaming.md", - "sha256": "fa8d20977ad9cd392f3a7e62ec969a42129bbadacec340110e7c0c56b1e99a13", - "size": 10836 + "sha256": "7655d35e839ae089521f5b8f641c30eb263f147e02c4b59e59037b900ebc0f75", + "size": 11528 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/context-windows", @@ -358,456 +218,491 @@ "url": "https://platform.claude.com/docs/en/build-with-claude/compaction", "status": "success", "path": "en/build-with-claude/compaction.md", - "sha256": "5e63ea97fcbae8dcc4714e1e2c2d1e1f777a57cd074bf686ab20b12fce064368", - "size": 95723 + "sha256": "2e89d7d810212e19aa5e4fd1cbb320726eb9d3f98aa2004472937f046385b8c5", + "size": 100552 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/context-editing", "status": "success", "path": "en/build-with-claude/context-editing.md", - "sha256": "ee16690987f0c061ce5f5aa69de8cb943a9073999f7aff3f739dcfcc1542202d", - "size": 76453 + "sha256": "8fbd0328f940abaa8e382dd4414780804b8a8753f57dfd86ba3c53e4520aef12", + "size": 79733 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching", "status": "success", "path": "en/build-with-claude/prompt-caching.md", - "sha256": "88a84f107e1234efe53b61c0966e39c8900f0616474a4748a8f585bb8d13f8e6", - "size": 113085 + "sha256": "6701067cdaa580f900fdfa40763bbc7e30084ea38de52a4f2b80ef428e18301a", + "size": 117892 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/token-counting", "status": "success", "path": "en/build-with-claude/token-counting.md", - "sha256": "c484adfe514ebb645ef12d535ad70d9ce68f1a1cc04d066e3917a6cb7961127d", - "size": 41549 + "sha256": "62a9fd208c940b247cf0b36e3831c73da34a04664e5eba460805e85322fcb1c5", + "size": 43759 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/files", "status": "success", "path": "en/build-with-claude/files.md", - "sha256": "dd96f5b53d5bb408f8e8d456f8579b02b2fa3b1ab5fa3f4636e39c92f35514e0", - "size": 26624 + "sha256": "8f86a2e46a35c8ca2aacabe52da4f3eb09df3274b81a919d0bfc854b1cc2c7e8", + "size": 27867 + }, + { + "url": "https://platform.claude.com/docs/en/build-with-claude/pdf-support", + "status": "success", + "path": "en/build-with-claude/pdf-support.md", + "sha256": "ae0cf46a3bf8e1df0442f2a3dad9ab235aa76c91f9d75a19aa1aafcd4fc39de4", + "size": 38560 + }, + { + "url": "https://platform.claude.com/docs/en/build-with-claude/vision", + "status": "success", + "path": "en/build-with-claude/vision.md", + "sha256": "5d34bbc1299d32522b8bc35824e64629bba4b3d2f01d94107f6a6fcbc8a721bf", + "size": 50353 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview", "status": "success", "path": "en/agents-and-tools/agent-skills/overview.md", - "sha256": "a1a6238d0381c6ea66cb0d2b902b22f4e0f454207739fe1e2d270720f7543580", - "size": 18850 + "sha256": "a6ba167cbe3cd3d5464eaaad762d5b1ef8e17fca55b771fec376f740a7c4ed63", + "size": 18221 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart", "status": "success", "path": "en/agents-and-tools/agent-skills/quickstart.md", - "sha256": "da27b0b27a12d5ce700e94f7801d65a2fa4c716b5ebd1f0652f59dc69b9e96cd", - "size": 14494 + "sha256": "2131bf5438c9e1bf5360b8ae7edcfdc1330f0de327644e5b007e557c94f9e934", + "size": 16770 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices", "status": "success", "path": "en/agents-and-tools/agent-skills/best-practices.md", - "sha256": "a18fc6d0b3d803da50de339176bfc6a147f3bec350292bbd7f821899af5a18f3", - "size": 41544 + "sha256": "d1da876439d60b3c813f6fac53745a0b518a7cc4af7973e6e9318dda64bee23a", + "size": 41372 }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise", "status": "success", "path": "en/agents-and-tools/agent-skills/enterprise.md", - "sha256": "99ba22e3083e4431ab1bc5c29197cb67cd89687d8e9f6045361a66a1a2034db6", - "size": 12762 - }, - { - "url": "https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill", - "status": "success", - "path": "en/agents-and-tools/agent-skills/claude-api-skill.md", - "sha256": "e9c9ec279e6a19bb1641a5b50907cf34fa5a10ff257b6da6d61abc729d6c920f", - "size": 5772 + "sha256": "6168dda2cca527a98efb5609477325d9cd4b4f5f2e297eb9aad5e563d3f5d9b8", + "size": 12590 }, { "url": "https://platform.claude.com/docs/en/build-with-claude/skills-guide", "status": "success", "path": "en/build-with-claude/skills-guide.md", - "sha256": "4b465dc6cbe05bc7a5401a035fb0d26183fcbc9653a0db12bb96b19ccb69f729", - "size": 144532 + "sha256": "b013a3cc251f20972d3f337fbbfdaa0f1ef5581689b916877e694d7a56fee79e", + "size": 153861 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/overview", + "url": "https://platform.claude.com/docs/en/agents-and-tools/remote-mcp-servers", "status": "success", - "path": "en/agent-sdk/overview.md", - "sha256": "a669e5898baf51eef7c02874a71c7c4cccd38deb1770706b6eeec64332d658cb", - "size": 20184 + "path": "en/agents-and-tools/remote-mcp-servers.md", + "sha256": "42aeab377e3bd764a9661a58119f60b92a3da01cdcd96feefd935df1c4b47c98", + "size": 1271 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/quickstart", + "url": "https://platform.claude.com/docs/en/agents-and-tools/mcp-connector", "status": "success", - "path": "en/agent-sdk/quickstart.md", - "sha256": "44af28401c2657c00771b63725e7653ac344393471597eb448eb6f237aaf6d76", - "size": 11761 + "path": "en/agents-and-tools/mcp-connector.md", + "sha256": "3e2f7aa9524eebfb99133ff19548e1abd9b7ca568e6db726a4cd6aa38d134b26", + "size": 25256 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/agent-loop", + "url": "https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview", "status": "success", - "path": "en/agent-sdk/agent-loop.md", - "sha256": "5ff1a7faa5019f1e1577673bf7c9f68d10dcd0880498831b9abf0db3bcccdb30", - "size": 29640 + "path": "en/build-with-claude/prompt-engineering/overview.md", + "sha256": "1ab62e934b9215243b1088059525048e47411f6758feb4ad397f50afcf53ed6b", + "size": 2392 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/claude-code-features", + "url": "https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices", "status": "success", - "path": "en/agent-sdk/claude-code-features.md", - "sha256": "f595aa5cedf1681c04fc2542601942372e90b5c5c50eae7412df2880f808d7bb", - "size": 15571 + "path": "en/build-with-claude/prompt-engineering/claude-prompting-best-practices.md", + "sha256": "6de2d20ca96d4d0886a33080dfc79e56a66b60f6409dbc77ebe3afc99cf1e43f", + "size": 46888 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/sessions", + "url": "https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-tools", "status": "success", - "path": "en/agent-sdk/sessions.md", - "sha256": "0d6a4e835798d7e1cde70a96ceaec5a78c13513b79540c7320396f50cd527075", - "size": 16173 + "path": "en/build-with-claude/prompt-engineering/prompting-tools.md", + "sha256": "91eb182b1eda6cfba521739fdfff08de17d773c224a735a66ec5f84e0ae7577f", + "size": 10236 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/streaming-vs-single-mode", + "url": "https://platform.claude.com/docs/en/test-and-evaluate/develop-tests", "status": "success", - "path": "en/agent-sdk/streaming-vs-single-mode.md", - "sha256": "a3944aabf53a03f1f7506bf63c35533bc0f5c8ff166c45bde3f8a7c9e315543c", - "size": 7648 + "path": "en/test-and-evaluate/develop-tests.md", + "sha256": "f53d8f3ae7a46cae179b8b3472bf1de9e05060914a69baf5dc3579e3d08984cc", + "size": 27264 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/streaming-output", + "url": "https://platform.claude.com/docs/en/test-and-evaluate/eval-tool", "status": "success", - "path": "en/agent-sdk/streaming-output.md", - "sha256": "6d4e5bbd00786b37f5d5dd6c00204107b158b7e74c1d52fb0c82285c77e2b923", - "size": 14637 + "path": "en/test-and-evaluate/eval-tool.md", + "sha256": "c4e35d37b91ddff07c53cb655c84cb1a13570de04328b3382dfeb96a65c4c614", + "size": 5418 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/mcp", + "url": "https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latency", "status": "success", - "path": "en/agent-sdk/mcp.md", - "sha256": "db0b8f60c77944c3dfa47edc12d3191d03ea442d6a0fabb490b7367c09ae3009", - "size": 23175 + "path": "en/test-and-evaluate/strengthen-guardrails/reduce-latency.md", + "sha256": "322e8242bcffa4ca042bd15971e9d8b1b24b67ba86c98c1ad173d98f06b3872e", + "size": 5221 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/custom-tools", + "url": "https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations", "status": "success", - "path": "en/agent-sdk/custom-tools.md", - "sha256": "37edf161dd83eb1f82308527b70bdff3f725eb037c90f896078c159b59928626", - "size": 31496 + "path": "en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations.md", + "sha256": "32760d421159fe18dc2c87912338efeab5582a43f66aa5a5d2adef3c7d834074", + "size": 3732 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/tool-search", + "url": "https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency", "status": "success", - "path": "en/agent-sdk/tool-search.md", - "sha256": "f97abbe892a6d553c83d05fcf3ed859cccb7fd4511b622416e1213e8a4be91d4", - "size": 6349 + "path": "en/test-and-evaluate/strengthen-guardrails/increase-consistency.md", + "sha256": "d52112e5bf7003f6f14a81bfcc6cd1ba4a012f3b4c394b3caf101bc25a1fcc43", + "size": 14351 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/permissions", + "url": "https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks", "status": "success", - "path": "en/agent-sdk/permissions.md", - "sha256": "010617ce8d02c108a61878c6238a4ee034d815d259cdb3b699d2f59efdaee0d5", - "size": 10982 + "path": "en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks.md", + "sha256": "19976860e0270df8f58366c46d9ac25e2f87b42d7ecf81d14c708508518aa110", + "size": 4699 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/user-input", + "url": "https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-prompt-leak", "status": "success", - "path": "en/agent-sdk/user-input.md", - "sha256": "e6e173cbbad614a83010b94dd4bfdc103a8c32b1828331c2063cf4980e3557cf", - "size": 31278 + "path": "en/test-and-evaluate/strengthen-guardrails/reduce-prompt-leak.md", + "sha256": "8c621321a8b5942ce0ce990687a5973919c04482a300a7852f5dcaafcc74d41e", + "size": 3090 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/hooks", + "url": "https://platform.claude.com/docs/en/about-claude/glossary", "status": "success", - "path": "en/agent-sdk/hooks.md", - "sha256": "8d87a3278b8c43a0084f1ecf14cc29390033f9154aea8f08f18ba87022baf1af", - "size": 34438 + "path": "en/about-claude/glossary.md", + "sha256": "1405208f57672548ba8389fec2db9a8cd4ec5baa99ecb09a08956b7929a1c55b", + "size": 9009 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/file-checkpointing", + "url": "https://platform.claude.com/docs/en/about-claude/use-case-guides/overview", "status": "success", - "path": "en/agent-sdk/file-checkpointing.md", - "sha256": "49de7438ae25bbe0d8c29bc6df64d3ea4fea22a51047c40884deb8820ae35361", - "size": 26386 + "path": "en/about-claude/use-case-guides/overview.md", + "sha256": "43239e353a3665f7f27444745f3ff3b76094016a7948fb6de3b2565925404d0b", + "size": 1108 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/structured-outputs", + "url": "https://platform.claude.com/docs/en/about-claude/use-case-guides/ticket-routing", "status": "success", - "path": "en/agent-sdk/structured-outputs.md", - "sha256": "b9da19e74fe263e29989107968609ad796ca8e8f16057a6e7f8c5f868b9f4464", - "size": 15153 + "path": "en/about-claude/use-case-guides/ticket-routing.md", + "sha256": "95526bdf0d535c79aaec136ed81f0ee05620a37d4c1c0cb168b1f39cc68935fa", + "size": 29672 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/hosting", + "url": "https://platform.claude.com/docs/en/about-claude/use-case-guides/customer-support-chat", "status": "success", - "path": "en/agent-sdk/hosting.md", - "sha256": "c0bbac46e2b5eff122cdd8ddc99491f5756fd9b01b7eb88fdbca8a275d5914ce", - "size": 6785 + "path": "en/about-claude/use-case-guides/customer-support-chat.md", + "sha256": "9a135f75f371fe2595a34d32f83b8e396f7092f144911d5febed74503d566567", + "size": 33730 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/secure-deployment", + "url": "https://platform.claude.com/docs/en/about-claude/use-case-guides/content-moderation", "status": "success", - "path": "en/agent-sdk/secure-deployment.md", - "sha256": "5a41396db7c36373e93d2f0645427c39babb1e22ecc2e6e72d51c0daab34523f", - "size": 21078 + "path": "en/about-claude/use-case-guides/content-moderation.md", + "sha256": "5ac9b36d2e8c4a555d348b5e72c211932939b3c2a79cef97aaa840f3cf15bc03", + "size": 25358 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/modifying-system-prompts", + "url": "https://platform.claude.com/docs/en/about-claude/use-case-guides/legal-summarization", "status": "success", - "path": "en/agent-sdk/modifying-system-prompts.md", - "sha256": "5d2b8c4e874974a75cb40fa969c513c1aba870e3e2ad88c32c478c46ac4ccc02", - "size": 15014 + "path": "en/about-claude/use-case-guides/legal-summarization.md", + "sha256": "17cbb01d881b2990978dcfd55a5eb87183d36867a0243fb9c531fbd1d5a90b83", + "size": 21702 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/subagents", + "url": "https://platform.claude.com/docs/en/release-notes/overview", "status": "success", - "path": "en/agent-sdk/subagents.md", - "sha256": "33231d55a08935113bc8ae17a112c219ea50a596fcd3ce7e140a268af4328d37", - "size": 25042 + "path": "en/release-notes/overview.md", + "sha256": "7f09add846740c12ad2d22fa0cb6de05286759f833e1fa9717b8e7fdf574856d", + "size": 39224 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/slash-commands", + "url": "https://platform.claude.com/docs/en/managed-agents/overview", "status": "success", - "path": "en/agent-sdk/slash-commands.md", - "sha256": "3be47dec9405284b44e1f23371e6ba1383f1bb494e8569b9832a24d1ec78da98", - "size": 13172 + "path": "en/managed-agents/overview.md", + "sha256": "52ca456014fa9569533b03db76576d2eacd71135331ee46325384d32385dd23b", + "size": 5646 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/skills", + "url": "https://platform.claude.com/docs/en/managed-agents/quickstart", "status": "success", - "path": "en/agent-sdk/skills.md", - "sha256": "1fc8fe2f562fb8d7426167c59ad7b6186942e8d09f1fb44a19d307327a1f7a80", - "size": 10689 + "path": "en/managed-agents/quickstart.md", + "sha256": "6ec3a69b8e4cd1eba6a86e33e133a273532e383f2ead716c3c0e8a0a0fae9c48", + "size": 23977 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/cost-tracking", + "url": "https://platform.claude.com/docs/en/managed-agents/onboarding", "status": "success", - "path": "en/agent-sdk/cost-tracking.md", - "sha256": "c108031b0d7fb88b18856f041c484ec0198d3500cab29cfb50c2bc4fa9ae8530", - "size": 11381 + "path": "en/managed-agents/onboarding.md", + "sha256": "8df87205bd38cb099e205174476958cccef251455d096cf8f06a653c12360de8", + "size": 4025 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/todo-tracking", + "url": "https://platform.claude.com/docs/en/managed-agents/agent-setup", "status": "success", - "path": "en/agent-sdk/todo-tracking.md", - "sha256": "68a0609de5b8f3775de1c7e06c0ed605bd1854317d90aaa5b1f880e8184ddd37", - "size": 6015 + "path": "en/managed-agents/agent-setup.md", + "sha256": "fff2d904bee918fc84baf11021558817b94eff7b0929fa95becc4235624ccef7", + "size": 13885 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/plugins", + "url": "https://platform.claude.com/docs/en/managed-agents/tools", "status": "success", - "path": "en/agent-sdk/plugins.md", - "sha256": "4897e9b43e3bcc8c96487c7bd32f338c18de714486737b032aef343a1f994019", - "size": 10685 + "path": "en/managed-agents/tools.md", + "sha256": "21580e46b68fe6228271024f3f6ff39584d25b23fd088d58081c3485c3528ffc", + "size": 14484 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/typescript", + "url": "https://platform.claude.com/docs/en/managed-agents/mcp-connector", "status": "success", - "path": "en/agent-sdk/typescript.md", - "sha256": "e1d2216372120977e551bedf1aaef7438c617ec2c7c23660a18d3582e800abfa", - "size": 73223 + "path": "en/managed-agents/mcp-connector.md", + "sha256": "8401150371f4b464b65957e7751ed58c3838bfc35edd6db18bd4d983d0eed00c", + "size": 9724 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/typescript-v2-preview", + "url": "https://platform.claude.com/docs/en/managed-agents/permission-policies", "status": "success", - "path": "en/agent-sdk/typescript-v2-preview.md", - "sha256": "05c4aa2de2bbdc721dfe8121a25c30136121a219897ed8a10ac4ca40c7612d38", - "size": 10937 + "path": "en/managed-agents/permission-policies.md", + "sha256": "7f43690053ca80c01884703e05cbb7ab1076145190ff06b8b5330307525e9e34", + "size": 25580 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/python", + "url": "https://platform.claude.com/docs/en/managed-agents/skills", "status": "success", - "path": "en/agent-sdk/python.md", - "sha256": "7b7b4ce9287afb19156198aac7004148c777ea2a5b187ae2909067459cb8aac6", - "size": 113246 + "path": "en/managed-agents/skills.md", + "sha256": "6f5a9018995628e2f9de0fdf6ac419acc1f5511c85a4df3e11add145f9695689", + "size": 5971 }, { - "url": "https://platform.claude.com/docs/en/agent-sdk/migration-guide", + "url": "https://platform.claude.com/docs/en/managed-agents/environments", "status": "success", - "path": "en/agent-sdk/migration-guide.md", - "sha256": "4636a4d6a837c51eaf4174af53c12fa7428b4a805afdbe75a9b349ca986004d3", - "size": 9080 + "path": "en/managed-agents/environments.md", + "sha256": "8a675d3732d3cc83b01202691b254188e48344ea258442f31f887c53758562aa", + "size": 17133 }, { - "url": "https://platform.claude.com/docs/en/agents-and-tools/mcp-connector", + "url": "https://platform.claude.com/docs/en/managed-agents/cloud-containers", "status": "success", - "path": "en/agents-and-tools/mcp-connector.md", - "sha256": "2fbd7970a9b6097dfea30f617333e9e2fe1750f2ce71ec0e0ffbbe35db5644d1", - "size": 24944 + "path": "en/managed-agents/cloud-containers.md", + "sha256": "18695a12bff72365ab03c88e350b3fd6cc6a5a880c3cbbdb2443c2d4dec8ec77", + "size": 2166 }, { - "url": "https://platform.claude.com/docs/en/agents-and-tools/remote-mcp-servers", + "url": "https://platform.claude.com/docs/en/managed-agents/sessions", "status": "success", - "path": "en/agents-and-tools/remote-mcp-servers.md", - "sha256": "42aeab377e3bd764a9661a58119f60b92a3da01cdcd96feefd935df1c4b47c98", - "size": 1271 + "path": "en/managed-agents/sessions.md", + "sha256": "309763a513acee8a9987e88c4317e6bbd382fe9dc2bff98d3d3066e3ed91ec5b", + "size": 17271 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock", + "url": "https://platform.claude.com/docs/en/managed-agents/events-and-streaming", "status": "success", - "path": "en/build-with-claude/claude-in-amazon-bedrock.md", - "sha256": "27d2db331d9649a1e75de2dd31637db9d8fe6b64b0ff5cede008b0d8ef015923", - "size": 11412 + "path": "en/managed-agents/events-and-streaming.md", + "sha256": "a74e7e8d362c6e80f9aa4fb67467e4b35cc51a5eef4913e952a11709c08ef83f", + "size": 51864 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock", + "url": "https://platform.claude.com/docs/en/managed-agents/define-outcomes", "status": "success", - "path": "en/build-with-claude/claude-on-amazon-bedrock.md", - "sha256": "01ccd6388151bb8189a8c3514108af7f6091eb8386cad1cdceede1b8c57c9975", - "size": 28749 + "path": "en/managed-agents/define-outcomes.md", + "sha256": "8d50c2a236b5121a8644f2dae78287086870ad1e91e2de5145d8b047f168ae16", + "size": 19751 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry", + "url": "https://platform.claude.com/docs/en/managed-agents/vaults", "status": "success", - "path": "en/build-with-claude/claude-in-microsoft-foundry.md", - "sha256": "031d5f283e82e224f885c676db91d52071c200ae6c4102639374117327577a24", - "size": 20754 + "path": "en/managed-agents/vaults.md", + "sha256": "b3a92fd98d4397e2da1cbaee4832ce498196d6a6d640341d72328578cb11a0b1", + "size": 22217 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai", + "url": "https://platform.claude.com/docs/en/managed-agents/github", "status": "success", - "path": "en/build-with-claude/claude-on-vertex-ai.md", - "sha256": "3eec9a604ceb11bf980c2d48afd035963734b1a2933a8ffac7790926698901e8", - "size": 23407 + "path": "en/managed-agents/github.md", + "sha256": "c6026d8ce2beacc7c282025cd9471fb57e2c514513a0cb9954fe778f366f5829", + "size": 23516 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview", + "url": "https://platform.claude.com/docs/en/managed-agents/files", "status": "success", - "path": "en/build-with-claude/prompt-engineering/overview.md", - "sha256": "1ab62e934b9215243b1088059525048e47411f6758feb4ad397f50afcf53ed6b", - "size": 2392 + "path": "en/managed-agents/files.md", + "sha256": "43ad1f8588da809c165dc706c9dd4e52cf912e8368dffc65a97bdae565859db6", + "size": 18117 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-tools", + "url": "https://platform.claude.com/docs/en/managed-agents/memory", "status": "success", - "path": "en/build-with-claude/prompt-engineering/prompting-tools.md", - "sha256": "91eb182b1eda6cfba521739fdfff08de17d773c224a735a66ec5f84e0ae7577f", - "size": 10236 + "path": "en/managed-agents/memory.md", + "sha256": "15631817eacdac7aefc137bd0f3f312e3b3eddee601a3e086e470bf2b93e00fe", + "size": 37063 }, { - "url": "https://platform.claude.com/docs/en/test-and-evaluate/develop-tests", + "url": "https://platform.claude.com/docs/en/managed-agents/multi-agent", "status": "success", - "path": "en/test-and-evaluate/develop-tests.md", - "sha256": "f53d8f3ae7a46cae179b8b3472bf1de9e05060914a69baf5dc3579e3d08984cc", - "size": 27264 + "path": "en/managed-agents/multi-agent.md", + "sha256": "f4632ec8ed31078f1247afcd7e81d9952cb0e7a50741153fbe936bc947135e7b", + "size": 24156 }, { - "url": "https://platform.claude.com/docs/en/test-and-evaluate/eval-tool", + "url": "https://platform.claude.com/docs/en/build-with-claude/administration-api", "status": "success", - "path": "en/test-and-evaluate/eval-tool.md", - "sha256": "c4e35d37b91ddff07c53cb655c84cb1a13570de04328b3382dfeb96a65c4c614", - "size": 5418 + "path": "en/build-with-claude/administration-api.md", + "sha256": "d23302bcb818d5fb7f2101d31f87831f46590234d23d6870e9c9f9ab8f2479b3", + "size": 7811 }, { - "url": "https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latency", + "url": "https://platform.claude.com/docs/en/build-with-claude/workspaces", "status": "success", - "path": "en/test-and-evaluate/strengthen-guardrails/reduce-latency.md", - "sha256": "b86133508a37ca5c48ef2762d671329b17c0a23c910fa6231793de80ac2c53bc", - "size": 5207 + "path": "en/build-with-claude/workspaces.md", + "sha256": "713ddcfccb42812a5501d80f2b0defa6df26f742ca022265a8a521b2730846c4", + "size": 12472 }, { - "url": "https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations", + "url": "https://platform.claude.com/docs/en/build-with-claude/data-residency", "status": "success", - "path": "en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations.md", - "sha256": "32760d421159fe18dc2c87912338efeab5582a43f66aa5a5d2adef3c7d834074", - "size": 3732 + "path": "en/build-with-claude/data-residency.md", + "sha256": "d515a5238cb4e7c5676c5de9b86bff73c733899bc3c24ae8d7a877e51d4339ed", + "size": 8703 }, { - "url": "https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency", + "url": "https://platform.claude.com/docs/en/build-with-claude/api-and-data-retention", "status": "success", - "path": "en/test-and-evaluate/strengthen-guardrails/increase-consistency.md", - "sha256": "d52112e5bf7003f6f14a81bfcc6cd1ba4a012f3b4c394b3caf101bc25a1fcc43", - "size": 14351 + "path": "en/build-with-claude/api-and-data-retention.md", + "sha256": "f95c8db4938a1dd99c7b6f0ae4b52e001d805cb30549a816b8b8c33a2fc3ca37", + "size": 22288 }, { - "url": "https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks", + "url": "https://platform.claude.com/docs/en/build-with-claude/claude-code-analytics-api", "status": "success", - "path": "en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks.md", - "sha256": "19976860e0270df8f58366c46d9ac25e2f87b42d7ecf81d14c708508518aa110", - "size": 4699 + "path": "en/build-with-claude/claude-code-analytics-api.md", + "sha256": "8a6bec99447e6d2fa9928dcc4b63faf68c78bb4e081ec5c81d1e9ad64f5f4722", + "size": 11250 }, { - "url": "https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals", + "url": "https://platform.claude.com/docs/en/build-with-claude/usage-cost-api", "status": "success", - "path": "en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals.md", - "sha256": "7e435c6d28bf7b3af668ca0052394f44b46ae0d15c075c5b11dba98c07545216", - "size": 10245 + "path": "en/build-with-claude/usage-cost-api.md", + "sha256": "eb143a3d95490552ba968b0cacd7a603ba575873071139facb27a68c4a1e58f4", + "size": 13322 }, { - "url": "https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-prompt-leak", + "url": "https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock", "status": "success", - "path": "en/test-and-evaluate/strengthen-guardrails/reduce-prompt-leak.md", - "sha256": "8c621321a8b5942ce0ce990687a5973919c04482a300a7852f5dcaafcc74d41e", - "size": 3090 + "path": "en/build-with-claude/claude-on-amazon-bedrock.md", + "sha256": "40d062923e5804bd5dd1a8c88fb72241f110f675ad311f7df0408e7c5a1e43e6", + "size": 28957 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/administration-api", + "url": "https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry", "status": "success", - "path": "en/build-with-claude/administration-api.md", - "sha256": "d23302bcb818d5fb7f2101d31f87831f46590234d23d6870e9c9f9ab8f2479b3", - "size": 7811 + "path": "en/build-with-claude/claude-in-microsoft-foundry.md", + "sha256": "2a7584e48b73fd7e2f96d7c044ae185dea1309a188d8e1df432cb1f44c8316d0", + "size": 21152 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/data-residency", + "url": "https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai", "status": "success", - "path": "en/build-with-claude/data-residency.md", - "sha256": "b1278fdee89d33ce96f3304086c34ee421d00ec1e541b9da746a842ae3d9ce6e", - "size": 8433 + "path": "en/build-with-claude/claude-on-vertex-ai.md", + "sha256": "48f0fb6cc3854aba715c1a083b1c9cbe37a011e6700a823edecdeee243193b28", + "size": 23609 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/workspaces", + "url": "https://platform.claude.com/docs/en/managed-agents/migration", "status": "success", - "path": "en/build-with-claude/workspaces.md", - "sha256": "7196ce596dea74eac1c5f58c9f9a14ef6184c777b4ea97657c131dda34e9f15a", - "size": 12313 + "path": "en/managed-agents/migration.md", + "sha256": "0fa85ce009531c3253e4fee180f9b8f00e7ad234b2c3ce4feecb2f15fcdc42de", + "size": 27677 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/usage-cost-api", + "url": "https://platform.claude.com/docs/en/managed-agents/observability", "status": "success", - "path": "en/build-with-claude/usage-cost-api.md", - "sha256": "eb143a3d95490552ba968b0cacd7a603ba575873071139facb27a68c4a1e58f4", - "size": 13322 + "path": "en/managed-agents/observability.md", + "sha256": "4cebacf6c95de773d96a86ad458ff854fb6fe169f9cc9073faf7b74200181f9e", + "size": 13162 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/claude-code-analytics-api", + "url": "https://platform.claude.com/docs/en/about-claude/models/overview", "status": "success", - "path": "en/build-with-claude/claude-code-analytics-api.md", - "sha256": "8a6bec99447e6d2fa9928dcc4b63faf68c78bb4e081ec5c81d1e9ad64f5f4722", - "size": 11250 + "path": "en/about-claude/models/overview.md", + "sha256": "db4358115c019eb7eb23012ec34de4ba0683159aa25a96b626f8f0e5d565c560", + "size": 10037 }, { - "url": "https://platform.claude.com/docs/en/build-with-claude/api-and-data-retention", + "url": "https://platform.claude.com/docs/en/about-claude/models/choosing-a-model", "status": "success", - "path": "en/build-with-claude/api-and-data-retention.md", - "sha256": "b40a6c17fb3bff3cbf719b0120b2421517f84967a5e82060a10490788dbd6b51", - "size": 22340 + "path": "en/about-claude/models/choosing-a-model.md", + "sha256": "96c928e062ca62bc43029b5b68166cb7c0e2e46a22f25ff3de68cc1c722813d2", + "size": 4348 }, { - "url": "https://platform.claude.com/docs/en/api/overview", + "url": "https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-6", "status": "success", - "path": "en/api/overview.md", - "sha256": "a20b9ab4a4731c8f7a049fc4d05c1e4f885b7f60b5ec83edd8298eab726ab023", - "size": 8848 + "path": "en/about-claude/models/whats-new-claude-4-6.md", + "sha256": "da607a8b04577fae1d51236c8e917de343a6783b4858d95bc4473c88cb33b7af", + "size": 9825 }, { - "url": "https://platform.claude.com/docs/en/api/beta-headers", + "url": "https://platform.claude.com/docs/en/about-claude/models/migration-guide", "status": "success", - "path": "en/api/beta-headers.md", - "sha256": "acbea77d44d7ffdff6d46fd8292d8db11dfd8323ed3ae8c7843c66fcc6eb4977", - "size": 2982 + "path": "en/about-claude/models/migration-guide.md", + "sha256": "2ced9168d6a1abc93e792020574330c580ae009a1e2a687bb668bf8dcf69a906", + "size": 46740 }, { - "url": "https://platform.claude.com/docs/en/api/errors", + "url": "https://platform.claude.com/docs/en/about-claude/model-deprecations", "status": "success", - "path": "en/api/errors.md", - "sha256": "ec2bdfd204bc452f97839fde634e4edf14373b95a05d11a448aeca83fe6ef609", - "size": 6722 + "path": "en/about-claude/model-deprecations.md", + "sha256": "cebc827b87f099d1c5f132fb76e95cc707451139199787123018263346d1c403", + "size": 9176 + }, + { + "url": "https://platform.claude.com/docs/en/resources/overview", + "status": "success", + "path": "en/resources/overview.md", + "sha256": "68da2bcc5c51e039029dd8625879914a2671e5693762a7dcccc9a6ac76c3d5aa", + "size": 3177 + }, + { + "url": "https://platform.claude.com/docs/en/release-notes/system-prompts", + "status": "success", + "path": "en/release-notes/system-prompts.md", + "sha256": "688eebd75e8703bbe002655b7fbdb37215ea6d8276e5fff6c8370fe6b8c81d40", + "size": 369074 + }, + { + "url": "https://platform.claude.com/docs/en/about-claude/pricing", + "status": "success", + "path": "en/about-claude/pricing.md", + "sha256": "1ceb301eb46b4c8a5de640a7f5214fe39a30ed7682170086fd08539d5df5df01", + "size": 22439 }, { "url": "https://platform.claude.com/docs/en/api/client-sdks", "status": "success", "path": "en/api/client-sdks.md", - "sha256": "ccf1f17a782d130f28057df9eb9e7d7b9a08009dfde933b4ffe5e76e8eb51a65", - "size": 7967 + "sha256": "42500dbbe9330bbf917bd6bb50e5b7e951f91eab49340311f43467588112eb65", + "size": 8505 + }, + { + "url": "https://platform.claude.com/docs/en/api/sdks/cli", + "status": "success", + "path": "en/api/sdks/cli.md", + "sha256": "10652b99706389d43cddae143b205ecd99e1efea62cbc3642ed595fc5d77d2dc", + "size": 16628 }, { "url": "https://platform.claude.com/docs/en/api/sdks/python", @@ -827,7 +722,7 @@ "url": "https://platform.claude.com/docs/en/api/sdks/java", "status": "success", "path": "en/api/sdks/java.md", - "sha256": "4519bcce13f61361efe7fe8270557e45f43323a89c976ee16125c5009b3be728", + "sha256": "bcb3ce24ec026d3332b106154f744fb98c8ecc72b6a3fd36af3d57fd6cfae2c2", "size": 44196 }, { @@ -841,8 +736,8 @@ "url": "https://platform.claude.com/docs/en/api/sdks/ruby", "status": "success", "path": "en/api/sdks/ruby.md", - "sha256": "f07fc188220e79a2639236ffa08afc322552a3fea695a2d067cb582049a8ff44", - "size": 13362 + "sha256": "de860a0859e8270a7096425c827b146049fbfa04258155cdfc7a0a965778b307", + "size": 13318 }, { "url": "https://platform.claude.com/docs/en/api/sdks/csharp", @@ -858,41 +753,6 @@ "sha256": "d0496b4436ad3fd6619b40d89d196dce45fa829257e9bd00bc4658f6987cb4ec", "size": 7018 }, - { - "url": "https://platform.claude.com/docs/en/api/rate-limits", - "status": "success", - "path": "en/api/rate-limits.md", - "sha256": "6304190afaf410f39ada62498645207e126abdf15c9c996901e16107e9d22758", - "size": 26297 - }, - { - "url": "https://platform.claude.com/docs/en/api/service-tiers", - "status": "success", - "path": "en/api/service-tiers.md", - "sha256": "6f081b4bb132610e8cd9dbecbea8dc4c6f1a6b23131384125c8c6f84fd281fe4", - "size": 5575 - }, - { - "url": "https://platform.claude.com/docs/en/api/versioning", - "status": "success", - "path": "en/api/versioning.md", - "sha256": "426fd21267dbafb4f231f71fbb28ba3edc2d265fddab6b0ae7ee1c8538ecf2b6", - "size": 1639 - }, - { - "url": "https://platform.claude.com/docs/en/api/ip-addresses", - "status": "success", - "path": "en/api/ip-addresses.md", - "sha256": "cc3c763ed7e1903ab2e670e5cf9ef8a578ce59194dcf9b1e57626762c2eafec0", - "size": 913 - }, - { - "url": "https://platform.claude.com/docs/en/api/supported-regions", - "status": "success", - "path": "en/api/supported-regions.md", - "sha256": "efff04f8b82996c132cd66435bcaa55ec0066240de3d3e8222af1399988aea7c", - "size": 2241 - }, { "url": "https://platform.claude.com/docs/en/api/openai-sdk", "status": "success", @@ -901,116 +761,109 @@ "size": 12088 }, { - "url": "https://platform.claude.com/docs/en/resources/overview", - "status": "success", - "path": "en/resources/overview.md", - "sha256": "68da2bcc5c51e039029dd8625879914a2671e5693762a7dcccc9a6ac76c3d5aa", - "size": 3177 - }, - { - "url": "https://platform.claude.com/docs/en/about-claude/glossary", + "url": "https://platform.claude.com/docs/en/api/overview", "status": "success", - "path": "en/about-claude/glossary.md", - "sha256": "1405208f57672548ba8389fec2db9a8cd4ec5baa99ecb09a08956b7929a1c55b", - "size": 9009 + "path": "en/api/overview.md", + "sha256": "23fbbb5510eddc47986a5a65cb3ca74d5481f4443431a86899f26def34596c70", + "size": 7543 }, { - "url": "https://platform.claude.com/docs/en/release-notes/system-prompts", + "url": "https://platform.claude.com/docs/en/api/beta-headers", "status": "success", - "path": "en/release-notes/system-prompts.md", - "sha256": "688eebd75e8703bbe002655b7fbdb37215ea6d8276e5fff6c8370fe6b8c81d40", - "size": 369074 + "path": "en/api/beta-headers.md", + "sha256": "19103d593aea77c0ae69aa9e01385b93d91dded83b163d12f0e8bfc3039c5818", + "size": 3606 }, { - "url": "https://platform.claude.com/docs/en/about-claude/use-case-guides/overview", + "url": "https://platform.claude.com/docs/en/api/errors", "status": "success", - "path": "en/about-claude/use-case-guides/overview.md", - "sha256": "43239e353a3665f7f27444745f3ff3b76094016a7948fb6de3b2565925404d0b", - "size": 1108 + "path": "en/api/errors.md", + "sha256": "663e1ead08480e0a38a8e7dc85e80e49bab7c5fb6eff5c5d4b6f536ff0c23684", + "size": 6945 }, { - "url": "https://platform.claude.com/docs/en/about-claude/use-case-guides/ticket-routing", + "url": "https://platform.claude.com/docs/en/api/rate-limits", "status": "success", - "path": "en/about-claude/use-case-guides/ticket-routing.md", - "sha256": "56311f9bb3cd1f84a2bc088b626740ffe4a858065285a73d93212872993c1265", - "size": 29658 + "path": "en/api/rate-limits.md", + "sha256": "f55461470e4f0952eda3c20b533c6506e56abf29f72d8bc8034c6a05cb6e2b73", + "size": 26686 }, { - "url": "https://platform.claude.com/docs/en/about-claude/use-case-guides/customer-support-chat", + "url": "https://platform.claude.com/docs/en/api/service-tiers", "status": "success", - "path": "en/about-claude/use-case-guides/customer-support-chat.md", - "sha256": "9a135f75f371fe2595a34d32f83b8e396f7092f144911d5febed74503d566567", - "size": 33730 + "path": "en/api/service-tiers.md", + "sha256": "2e86065494139b593e4798f4b67e327653843379fec766c7767737e490477444", + "size": 5582 }, { - "url": "https://platform.claude.com/docs/en/about-claude/use-case-guides/content-moderation", + "url": "https://platform.claude.com/docs/en/api/versioning", "status": "success", - "path": "en/about-claude/use-case-guides/content-moderation.md", - "sha256": "e79bc43acaa889c4955f0c913b3cf8bacb9e2d52d788a3ceedbe9e0aeb9d5691", - "size": 25329 + "path": "en/api/versioning.md", + "sha256": "f7848bbf23822ff845b28fbe28f5c2ad26627d93f8fde03b7d48b6c7e254acac", + "size": 1657 }, { - "url": "https://platform.claude.com/docs/en/about-claude/use-case-guides/legal-summarization", + "url": "https://platform.claude.com/docs/en/api/ip-addresses", "status": "success", - "path": "en/about-claude/use-case-guides/legal-summarization.md", - "sha256": "56eadda92a6ff3441bcda9cbec2710a1f8aabbf21aa7f3954503177f6b35da53", - "size": 21688 + "path": "en/api/ip-addresses.md", + "sha256": "cc3c763ed7e1903ab2e670e5cf9ef8a578ce59194dcf9b1e57626762c2eafec0", + "size": 913 }, { - "url": "https://platform.claude.com/docs/en/release-notes/overview", + "url": "https://platform.claude.com/docs/en/api/supported-regions", "status": "success", - "path": "en/release-notes/overview.md", - "sha256": "701cb7908ba0c1b30ca959f08c696eb480e19b7a4946ee96c3872277842497cd", - "size": 38509 + "path": "en/api/supported-regions.md", + "sha256": "efff04f8b82996c132cd66435bcaa55ec0066240de3d3e8222af1399988aea7c", + "size": 2241 }, { "url": "https://platform.claude.com/docs/en/api/completions", "status": "success", "path": "en/api/completions.md", - "sha256": "172aea891cf5a1fd881b339103cceddd97dd507272d898bbc41f25613c68b1ef", - "size": 11541 + "sha256": "86667d7b7bf2d3118f4b6760c8cdb5675acacaaca374ca060ceb16557dcb5ea5", + "size": 11858 }, { "url": "https://platform.claude.com/docs/en/api/completions/create", "status": "success", "path": "en/api/completions/create.md", - "sha256": "a2dea0a4c840acce2bf49963c90bac3170c1a640292a81ac4ef9ea93cf44de7b", - "size": 8964 + "sha256": "232244d49370abb9a09078e4598fef802e6e072e2f6c59ae82d373b7f2113042", + "size": 9164 }, { "url": "https://platform.claude.com/docs/en/api/messages", "status": "success", "path": "en/api/messages.md", - "sha256": "bb0ff317904c110a9abe768ed5385e1ade18167ed10002a9c62879657a260bf3", - "size": 897401 + "sha256": "444d6858f3d62fa6e4058f3eff76fff40ccb0c222e70b8fb37dde95517cc2051", + "size": 898856 }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "status": "success", "path": "en/api/messages/create.md", - "sha256": "533046bb19826e4cd7b0083c4624aeb056a5c4ceadd231ee677292c070613250", - "size": 122130 + "sha256": "aafae94a53651303c80eb77b1531d46ff6d92f5215a01a12743d9fe4f3f99136", + "size": 122360 }, { "url": "https://platform.claude.com/docs/en/api/messages/count_tokens", "status": "success", "path": "en/api/messages/count_tokens.md", - "sha256": "323cd2875b9ad11da145457900d2cf7fc0ebc16e16b3de535fe2f7adfc762ea4", - "size": 96728 + "sha256": "10be790030adbfb0c622fc846f8469431644392d82d8bac6d17fc3fa23b1b550", + "size": 96847 }, { "url": "https://platform.claude.com/docs/en/api/messages/batches", "status": "success", "path": "en/api/messages/batches.md", - "sha256": "601377e6e3ae4a4bffb6a68d0bd3f5a5c5948d7953b8fe5596c46a77ee3f37e4", - "size": 235604 + "sha256": "95729648967e950b904959a9f378de9cea716005aac2670b20aed34ac9d86fd9", + "size": 236229 }, { "url": "https://platform.claude.com/docs/en/api/messages/batches/create", "status": "success", "path": "en/api/messages/batches/create.md", - "sha256": "6ffaaaf4a0f3121244138600261f81ee91a1739f5c590128c8f3276cb7b808ba", - "size": 111363 + "sha256": "89b1dc1d5cbf4243142c8e23ef561a12348eed489f804cc8a22ed265a640bbaa", + "size": 111484 }, { "url": "https://platform.claude.com/docs/en/api/messages/batches/retrieve", @@ -1044,3494 +897,6294 @@ "url": "https://platform.claude.com/docs/en/api/messages/batches/results", "status": "success", "path": "en/api/messages/batches/results.md", - "sha256": "d2e4da5349604b7b9e56fb915dedc4b639669143b681e623b22b99217e65a840", - "size": 28577 + "sha256": "d78446bfd805b16814c6aa1a910d1c7fd008c6c36fe8c363895878a949d4a681", + "size": 28706 }, { "url": "https://platform.claude.com/docs/en/api/models", "status": "success", "path": "en/api/models.md", - "sha256": "f86fad3c700a06dcfd10d8838c7c34d65d49c66038cef7f41afa37f23ee41d06", - "size": 23216 + "sha256": "78b104794e305ca2b79ac07ffa473f1f9b45ef92b2dec85d8a6d51d6aeab2c3d", + "size": 23144 }, { "url": "https://platform.claude.com/docs/en/api/models/list", "status": "success", "path": "en/api/models/list.md", - "sha256": "c09d807618785ff65ca01eb9b44585cf1befe2718c61676dcc6a9d0ac41ee344", - "size": 6469 + "sha256": "36b4a25a55529c9df47966dd289c014d697bdbc8ebb7082eaae7b736c865ef2b", + "size": 6433 }, { "url": "https://platform.claude.com/docs/en/api/models/retrieve", "status": "success", "path": "en/api/models/retrieve.md", - "sha256": "6a65e3554cabab2a1af71311d206de9d23dc17e6eb904b83774d76d3789b3756", - "size": 5818 + "sha256": "0f19a75c33720e90d80d4f35b92e3736bf10d7cae3adae9c9532a6c50d392a2f", + "size": 5782 }, { "url": "https://platform.claude.com/docs/en/api/beta", "status": "success", "path": "en/api/beta.md", - "sha256": "0a56c3fd7ccf2424d7efe3c7ca4f15e0c0dbe2382cc525d51ba5fdc3ec9cdedd", - "size": 1188825 + "sha256": "5a0dec8003effa8c821790f9e40ba34aa46a6f9a43ae62f454edb61b04655b6d", + "size": 1738643 }, { "url": "https://platform.claude.com/docs/en/api/beta/models", "status": "success", "path": "en/api/beta/models.md", - "sha256": "51dc5f5499e05437e2896227bdba34084e44075f28cfe6f97cf63ec69570f499", - "size": 23651 + "sha256": "af1874cefcd36cf680f59b28222cddc2d71a564f251b0132587721484db1564a", + "size": 23579 }, { "url": "https://platform.claude.com/docs/en/api/beta/models/list", "status": "success", "path": "en/api/beta/models/list.md", - "sha256": "4faa5b49a9cd85d2dcb3ad97b83ed4b94e535f142903dd856ede1e419509f60f", - "size": 6553 + "sha256": "5fe6d242b4d5be26655ccb839add218bbe2e4d25dbd55ce898c1176d17490eed", + "size": 6517 }, { "url": "https://platform.claude.com/docs/en/api/beta/models/retrieve", "status": "success", "path": "en/api/beta/models/retrieve.md", - "sha256": "d88760c7cbdb29b351c6677ad94d18c63f22db1352e80e2410a9af8d63d7a2c1", - "size": 5902 + "sha256": "8fd94f2b6b32b8339b294c85cd8abb663c780be894733c95b3f8a28baa540786", + "size": 5866 }, { "url": "https://platform.claude.com/docs/en/api/beta/messages", "status": "success", "path": "en/api/beta/messages.md", - "sha256": "0bb19b96d04020cb2607b64ce256c3695c7239ad0f3b6c04ae350e2e4f73dd97", - "size": 1112061 + "sha256": "62e5b4eb904f849b087a8747be6d511cf79be91700a7358de0727767d9216e6c", + "size": 1112786 }, { "url": "https://platform.claude.com/docs/en/api/beta/messages/create", "status": "success", "path": "en/api/beta/messages/create.md", - "sha256": "3f16b1363d0194eaa8bf94fee46b5f4303d3663cad427a39fde0d1b4db42e823", - "size": 153731 + "sha256": "5360225e03d7ac3c66c96f6e5a5971889288f4904169b96ac222a0819df63170", + "size": 153767 }, { "url": "https://platform.claude.com/docs/en/api/beta/messages/count_tokens", "status": "success", "path": "en/api/beta/messages/count_tokens.md", - "sha256": "9eab57d92b24cbe7f027da5acb6c9f737a0c56bf74465b63ea93d754fdeba416", - "size": 119322 + "sha256": "b2178b06a53f396a89ad73424ac16a74ebb20bb19a75c12e34d3b3cd3b0c1c3a", + "size": 119405 }, { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches", "status": "success", "path": "en/api/beta/messages/batches.md", - "sha256": "4d22404990bb278be2178275c0e62ab2c78c4ccc98f774e62b0fb54b222aa185", - "size": 303525 + "sha256": "1dba2af461d12c9dc3747c10b878c6813e90cfd772792a7f9117d1b2b81520b2", + "size": 303768 }, { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches/create", "status": "success", "path": "en/api/beta/messages/batches/create.md", - "sha256": "a4124411cfb44775d218a5e5b46d67552bfcbf972f283b1ac8b56a0491581e4c", - "size": 136234 + "sha256": "d5ee19d4610f51ccea5a32394f47d2a06bd8ce72c68a73dcae4db9c75ff5c1d9", + "size": 136153 }, { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches/retrieve", "status": "success", "path": "en/api/beta/messages/batches/retrieve.md", - "sha256": "ec4b4c463cb4568760f56b3080adfd2bbd5b1bf1dbeb534e520be2f40e4076d2", - "size": 4608 + "sha256": "0da65451d23fc323bfa98db7c3b4eb4f7835eb8a56cce01acc891e49524767e5", + "size": 4572 }, { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches/list", "status": "success", "path": "en/api/beta/messages/batches/list.md", - "sha256": "be943a5c8ec4f1743e8ac1fb553cecc1768a1f83af25d9444f2af96b12593418", - "size": 5120 + "sha256": "92e88a94a522d0d7ec99991f3c862fc51090e320b31db304f9cdc27f9dd909da", + "size": 5084 }, { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches/cancel", "status": "success", "path": "en/api/beta/messages/batches/cancel.md", - "sha256": "6107448f700894cc1d05cdd8489b233548743488b701fd951cc0aba5753a2b55", - "size": 4945 + "sha256": "03420745a264a8dd76376d027b1670a23410e84507797118280ad03168a1d48a", + "size": 4909 }, { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches/delete", "status": "success", "path": "en/api/beta/messages/batches/delete.md", - "sha256": "74834f88895232bfcd441fa20f7774fea8cab97c1e5535d2ccf95f00507672c1", - "size": 2063 + "sha256": "d91afc4abf2fbb795e1ca7be44a91166960b334deb52c03a8c70076d302bdfc8", + "size": 2027 }, { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches/results", "status": "success", "path": "en/api/beta/messages/batches/results.md", - "sha256": "26367ab9fc5ad3d468ae1b0a8f52ad9c2c624e372508c657fad0f7e650b78af3", - "size": 39262 + "sha256": "9fb6469e2cc3f92630455c25adfc75ede65d666ec2e693cf3c5c289913f3e08b", + "size": 39355 }, { - "url": "https://platform.claude.com/docs/en/api/beta/files", + "url": "https://platform.claude.com/docs/en/api/beta/agents", "status": "success", - "path": "en/api/beta/files.md", - "sha256": "087a774ac9f313d9360450426736730ea0cbdedcec3a658f89fe19aa040eb70f", - "size": 10817 + "path": "en/api/beta/agents.md", + "sha256": "069edcb785439a9718b1cde3d4b6ebd0cdd4d0bd005e6aaf015075a6946d1cb2", + "size": 105416 }, { - "url": "https://platform.claude.com/docs/en/api/beta/files/upload", + "url": "https://platform.claude.com/docs/en/api/beta/agents/create", "status": "success", - "path": "en/api/beta/files/upload.md", - "sha256": "d60fac3d5af65aa69c42c50fcbc1007052db0c0ce1dc9b2e77260fe784512420", - "size": 2048 + "path": "en/api/beta/agents/create.md", + "sha256": "32c35c08000d73af4f840ae9710538085762734e10dccc916e197e0bee50cc9e", + "size": 19091 }, { - "url": "https://platform.claude.com/docs/en/api/beta/files/list", + "url": "https://platform.claude.com/docs/en/api/beta/agents/list", "status": "success", - "path": "en/api/beta/files/list.md", - "sha256": "8fd406de7d4840e001381d3819e60c1a25361b1615d3438650865bc2456c9269", - "size": 2665 + "path": "en/api/beta/agents/list.md", + "sha256": "6db8b045e978fa98765bbdd71431545709767de86156f5644255280c2668bb0c", + "size": 9028 }, { - "url": "https://platform.claude.com/docs/en/api/beta/files/download", + "url": "https://platform.claude.com/docs/en/api/beta/agents/retrieve", "status": "success", - "path": "en/api/beta/files/download.md", - "sha256": "942f577b25dcd6e886f309be7bd577b2724e170c3cbdae600314179f869f5e90", - "size": 1439 + "path": "en/api/beta/agents/retrieve.md", + "sha256": "0d677fd4febc15ca321ca35d4539e05a0a46b4cae15b425a1d6e0f4ff735275d", + "size": 8688 }, { - "url": "https://platform.claude.com/docs/en/api/beta/files/retrieve_metadata", + "url": "https://platform.claude.com/docs/en/api/beta/agents/update", "status": "success", - "path": "en/api/beta/files/retrieve_metadata.md", - "sha256": "266093eb24bb0e8d71e70c6e7ee526be82026e5664c6ba9de0265bc5d3128b10", - "size": 2068 + "path": "en/api/beta/agents/update.md", + "sha256": "9fadd4168bca7d680865b8b022991697adcb29500e72d52e95b01c189e8386ae", + "size": 19720 }, { - "url": "https://platform.claude.com/docs/en/api/beta/files/delete", + "url": "https://platform.claude.com/docs/en/api/beta/agents/archive", "status": "success", - "path": "en/api/beta/files/delete.md", - "sha256": "83c59b4a72977c24892cc7f1f608b30138365ed059e7b516335a4c6360c879f4", - "size": 1681 + "path": "en/api/beta/agents/archive.md", + "sha256": "0dc7fbf1c49091d43e860855a014a8eb1ca4dd078015f03f063fa4480365ea07", + "size": 8585 }, { - "url": "https://platform.claude.com/docs/en/api/beta/skills", + "url": "https://platform.claude.com/docs/en/api/beta/agents/versions", "status": "success", - "path": "en/api/beta/skills.md", - "sha256": "ec8d6162e784ff398f03c6367ba155031ca41fd1dc6929d8230ee76343b0fa20", - "size": 26346 + "path": "en/api/beta/agents/versions.md", + "sha256": "05606144266683b03602fce9b121830cfb9e9af1882afc47c8e3050f074974fe", + "size": 8806 }, { - "url": "https://platform.claude.com/docs/en/api/beta/skills/create", + "url": "https://platform.claude.com/docs/en/api/beta/agents/versions/list", "status": "success", - "path": "en/api/beta/skills/create.md", - "sha256": "e5be729d0312312dcd3f67ee10545e1f78a08fcbde857780038ed589bb593431", - "size": 2200 + "path": "en/api/beta/agents/versions/list.md", + "sha256": "00eac1a44ea85b4464254d77b6e9bc13bb8023bf9266e4c796403fe1ef1fd618", + "size": 8794 }, { - "url": "https://platform.claude.com/docs/en/api/beta/skills/list", + "url": "https://platform.claude.com/docs/en/api/beta/environments", "status": "success", - "path": "en/api/beta/skills/list.md", - "sha256": "231840aa4f0fe004d84bccd314136eded80ab44ba84912c431f40647dc49891e", - "size": 3232 + "path": "en/api/beta/environments.md", + "sha256": "536704a977b1081128cfad46ecdd2ee7780fb701916abb99ab79f77d1cd6999a", + "size": 37911 }, { - "url": "https://platform.claude.com/docs/en/api/beta/skills/retrieve", + "url": "https://platform.claude.com/docs/en/api/beta/environments/create", "status": "success", - "path": "en/api/beta/skills/retrieve.md", - "sha256": "3f3134ae00cfb70b9653f21eb397d709682454a253c0543a3fc8804bb263382f", - "size": 2338 + "path": "en/api/beta/environments/create.md", + "sha256": "d9762779c973f861ea3f12cad5853894ede95e8ec46f4125179f1490ac9eca32", + "size": 6925 }, { - "url": "https://platform.claude.com/docs/en/api/beta/skills/delete", + "url": "https://platform.claude.com/docs/en/api/beta/environments/list", "status": "success", - "path": "en/api/beta/skills/delete.md", - "sha256": "0e20fc3ff1501f59ce5ec7874379871ffab4c49388fc23b20981c355fe1ac8ed", - "size": 1722 + "path": "en/api/beta/environments/list.md", + "sha256": "a384cb85a99cacd8701dd7028c5895f6918619628b17f8e1e18a6f5520b5c6e3", + "size": 4304 }, { - "url": "https://platform.claude.com/docs/en/api/beta/skills/versions", + "url": "https://platform.claude.com/docs/en/api/beta/environments/retrieve", "status": "success", - "path": "en/api/beta/skills/versions.md", - "sha256": "f0c309756dc9e0eed11d8fbdda70aef1ddeaced9ab3213a62d2f6cf1aba8bafa", - "size": 13606 + "path": "en/api/beta/environments/retrieve.md", + "sha256": "e992866883fa7d921c85760b0423f5624437cc38b07ca1a1f58015d5b83de0b1", + "size": 3960 }, { - "url": "https://platform.claude.com/docs/en/api/beta/skills/versions/create", + "url": "https://platform.claude.com/docs/en/api/beta/environments/update", "status": "success", - "path": "en/api/beta/skills/versions/create.md", - "sha256": "f9934b49e021653159e1a42c51859a508fb83644932a0517b8970e86d068fff6", - "size": 2461 + "path": "en/api/beta/environments/update.md", + "sha256": "7b134f244b7d42f2238c413af4bf5ceca51e08ba83785825f5d9fbed5295769c", + "size": 7011 }, { - "url": "https://platform.claude.com/docs/en/api/beta/skills/versions/list", + "url": "https://platform.claude.com/docs/en/api/beta/environments/delete", "status": "success", - "path": "en/api/beta/skills/versions/list.md", - "sha256": "e5cc2369e694fe57705a4c15489d2baa7c2a907c5cfd06f79ba96cdd5964b6a8", - "size": 3028 + "path": "en/api/beta/environments/delete.md", + "sha256": "92e30f6916093135a8f158c20831e34234138567ffa3a59b649dcffe134ec8d9", + "size": 1787 }, { - "url": "https://platform.claude.com/docs/en/api/beta/skills/versions/retrieve", + "url": "https://platform.claude.com/docs/en/api/beta/environments/archive", "status": "success", - "path": "en/api/beta/skills/versions/retrieve.md", - "sha256": "3fb8ecdf51ebed03fa634c51a9b638f855ec707382e0a007e64520543a557c2a", - "size": 2606 + "path": "en/api/beta/environments/archive.md", + "sha256": "22c4fc28d1fcb48efc67bacf8a836a54b52326ac46be65fc30a31291267e1b7e", + "size": 4042 }, { - "url": "https://platform.claude.com/docs/en/api/beta/skills/versions/delete", + "url": "https://platform.claude.com/docs/en/api/beta/sessions", "status": "success", - "path": "en/api/beta/skills/versions/delete.md", - "sha256": "4183c41d34f3d122dba12c0b63c7fcab407bb944ab66b72b24a8ed98a5d2bba4", - "size": 1956 + "path": "en/api/beta/sessions.md", + "sha256": "2cb6d5b232c909ec8863289f0c8ef63172ffaa45fd2df741fd033cb9997a7af2", + "size": 356070 }, { - "url": "https://platform.claude.com/docs/en/api/beta/user_profiles", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/create", "status": "success", - "path": "en/api/beta/user_profiles.md", - "sha256": "ce200a1a9d0303db4ba72501e42c39dd1e36d64ba7507d914f1f6f5e724128f2", - "size": 10455 + "path": "en/api/beta/sessions/create.md", + "sha256": "b843bcc309ca5517df1d4cf93f49b0e333f3bf5dd2abd35f826fcd3e04039618", + "size": 14492 }, { - "url": "https://platform.claude.com/docs/en/api/beta/user_profiles/create", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/list", "status": "success", - "path": "en/api/beta/user_profiles/create.md", - "sha256": "a65fa336bf46be02ad6058f50d8c92c8d081f2647a0c2f40145cf3a5a567a588", - "size": 2072 + "path": "en/api/beta/sessions/list.md", + "sha256": "287940708226c77e02bb8214c8f9182f7cc7e042e21ec887933f6b4e360e37cf", + "size": 12725 }, { - "url": "https://platform.claude.com/docs/en/api/beta/user_profiles/list", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/retrieve", "status": "success", - "path": "en/api/beta/user_profiles/list.md", - "sha256": "929957f5928e16872463b7ee6939b0aa84256d90457677950cff45c882cf818f", - "size": 1975 + "path": "en/api/beta/sessions/retrieve.md", + "sha256": "43476d95b271956a20e6532e7358f93366a41127ac2408a3ca7aa9ec55061a37", + "size": 11704 }, { - "url": "https://platform.claude.com/docs/en/api/beta/user_profiles/retrieve", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/update", "status": "success", - "path": "en/api/beta/user_profiles/retrieve.md", - "sha256": "020d9734138d8caa2c299c32f9ffec84ed6ab8df997dcc4d8288c7b15ad46ef5", - "size": 1795 + "path": "en/api/beta/sessions/update.md", + "sha256": "6f9ed61040d6b40d5844a6298c30bbd4a2bc66a6af5157bc285e69d5b055bb11", + "size": 12164 }, { - "url": "https://platform.claude.com/docs/en/api/beta/user_profiles/update", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/delete", "status": "success", - "path": "en/api/beta/user_profiles/update.md", - "sha256": "a668cac16338837049265a7d26429a33d879410d3b04102dc10bc428d261e9fe", - "size": 2208 + "path": "en/api/beta/sessions/delete.md", + "sha256": "b29e0ba057e5096596e3502a30775b58e04184f7a34690dd80c1c4b7dd440c6e", + "size": 1617 }, { - "url": "https://platform.claude.com/docs/en/api/beta/user_profiles/create_enrollment_url", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/archive", "status": "success", - "path": "en/api/beta/user_profiles/create_enrollment_url.md", - "sha256": "0e0d18e49fcef63b99dea3f45df8cee8f04cbc84cffedc81a80cb9c3050c8b43", - "size": 1658 + "path": "en/api/beta/sessions/archive.md", + "sha256": "84f4a8439570d94fe3637d63c29f9cc12fc7d664190f83a380f09ca772401a57", + "size": 11738 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/completions", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/events", "status": "success", - "path": "en/api/typescript/completions.md", - "sha256": "c3a4e6f18f8d30379663bfa910a4b4dea6638ddf3678ce62d7303b157c6ffcd6", - "size": 12168 + "path": "en/api/beta/sessions/events.md", + "sha256": "3b9c2b4aa5f9e897af538526096d448ea3eff9797f8ca1a25e9e1b0c180038e8", + "size": 252367 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/completions/create", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/events/list", "status": "success", - "path": "en/api/typescript/completions/create.md", - "sha256": "6a5fabec438558c76d8eef437ac211e68f8655e7016f8ec225048d434f2d5069", - "size": 9810 + "path": "en/api/beta/sessions/events/list.md", + "sha256": "22ac7ffd26607d0815041a48d106a61e3c0e5ce834ae56ffa28adaf47365e6de", + "size": 38293 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/messages", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/events/send", "status": "success", - "path": "en/api/typescript/messages.md", - "sha256": "fc4f6170bbec73dbdb30bc07792635b2e66575bee1ec026325c6df48fa47b7d2", - "size": 840569 + "path": "en/api/beta/sessions/events/send.md", + "sha256": "575b9cf443e91b28a1678b114bbcaba4fb3ec28b1d1d1bf4461f11f8c3f82540", + "size": 21195 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/messages/create", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/events/stream", "status": "success", - "path": "en/api/typescript/messages/create.md", - "sha256": "4388da4bf4b129d7bf53309c1f1a48ebdf4db779a8ee0dd8f7782ccfef14fac9", - "size": 121078 + "path": "en/api/beta/sessions/events/stream.md", + "sha256": "6bc2ac6f29d782f3d72485af335dfe2fc85d63d1d2b21b39da0b4d3eba9f90d6", + "size": 38000 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/resources", "status": "success", - "path": "en/api/typescript/messages/count_tokens.md", - "sha256": "7c22c072f5fa2012f395d85599dab3ffd4945004de93941244ce3300d7b73189", - "size": 92868 + "path": "en/api/beta/sessions/resources.md", + "sha256": "45141ee7877b34c444410a01d35b005cc7d967e7c3cd81e56d1992a2eeb961ce", + "size": 17655 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/resources/add", "status": "success", - "path": "en/api/typescript/messages/batches.md", - "sha256": "299d6fcb97a4ea0a7d2db0fc95cee91692b3805c9b8c69e05cfc252b7b2fbd69", - "size": 224172 + "path": "en/api/beta/sessions/resources/add.md", + "sha256": "b7de55ef9e25792e9ae3325a75124c881ce0e016871a832d508449fea872470f", + "size": 2097 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/resources/list", "status": "success", - "path": "en/api/typescript/messages/batches/create.md", - "sha256": "5986e866636ad3f2f70e0f0175dd09ae1a3174ad7bf044a757ac1ac986f0fda0", - "size": 107323 + "path": "en/api/beta/sessions/resources/list.md", + "sha256": "7b60fc43c5dd1d60aa053a3e39d2d8b64b09a31e48a3d22f59c977937be31369", + "size": 3016 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/resources/retrieve", "status": "success", - "path": "en/api/typescript/messages/batches/retrieve.md", - "sha256": "a46e305636c3469ef0de4772ddbf94a7047b36ff62dde8ea939b0d65e8f43634", - "size": 3637 + "path": "en/api/beta/sessions/resources/retrieve.md", + "sha256": "78694cab9e1880e7907c2c49b490fc3bcd89cdcd4ec34bfaed3c1c8ba9f354f3", + "size": 2570 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/resources/update", "status": "success", - "path": "en/api/typescript/messages/batches/list.md", - "sha256": "f08b6a4ebd48b6f1b3867e11374ac83f89ab802efbf4cf1ed05b42f9d0abbd8c", - "size": 3964 + "path": "en/api/beta/sessions/resources/update.md", + "sha256": "4b4115652bed69839a9288394c55d02ac2bd50e1c81822aa3bf1b48433de37e4", + "size": 2857 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/beta/sessions/resources/delete", "status": "success", - "path": "en/api/typescript/messages/batches/cancel.md", - "sha256": "a9b39fec2334f9cf14a3a68dff436006b889ecaf9b3f5b4d9252276422e8af90", - "size": 3949 + "path": "en/api/beta/sessions/resources/delete.md", + "sha256": "d5a1896fb32d0e7ddbb107f754f97b0407ce291368feb1e4ecde533027e8effd", + "size": 1698 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/beta/vaults", "status": "success", - "path": "en/api/typescript/messages/batches/delete.md", - "sha256": "119dfb75f469b9c2cf2b1c924b24d6b43af84ee6866f37933da5eaaad9da2159", - "size": 1107 + "path": "en/api/beta/vaults.md", + "sha256": "04d42ca03c05c4bd9be37fbff5b49cfbcedd76ac16893e78046a33f5e88e347d", + "size": 59143 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/create", "status": "success", - "path": "en/api/typescript/messages/batches/results.md", - "sha256": "7b46f643f5c2a52fb7d51181cae3fcebb175e4de235a3d2cc2069bcb477f6b5c", - "size": 26832 + "path": "en/api/beta/vaults/create.md", + "sha256": "355666e88235f2fc1370b2f1f7e4448a1adb0cdf7698bc65a08ed5167c54484a", + "size": 2209 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/models", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/list", "status": "success", - "path": "en/api/typescript/models.md", - "sha256": "bb205f61bf328904b8d3903f45782a94e685a5f13bd799ef95d7a2ff55ac7d72", - "size": 23255 + "path": "en/api/beta/vaults/list.md", + "sha256": "4dccc0e3c3c81f4200d3a13218781acc8d8479277fea18afa8018eecdf66924d", + "size": 2241 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/models/list", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/retrieve", "status": "success", - "path": "en/api/typescript/models/list.md", - "sha256": "f2b9c02a90fec89fa3a086f0a965002473802dbef5b59f09d2577acc46026d38", - "size": 6508 + "path": "en/api/beta/vaults/retrieve.md", + "sha256": "422652151889622460b5b3ca302c7e4c9268b9bf08c1b317dd0236cffe2582b7", + "size": 1969 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/update", "status": "success", - "path": "en/api/typescript/models/retrieve.md", - "sha256": "4f3cc381ef7ccc98386b65238c2845d2c6eba7b5b73c65de58193982b9d4d18a", - "size": 6050 + "path": "en/api/beta/vaults/update.md", + "sha256": "29bccb2e83e690bdd1cc0ef5d9c3d50d72ec1d2899a7252e633c4f60276f7241", + "size": 2291 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/delete", "status": "success", - "path": "en/api/typescript/beta.md", - "sha256": "a0894f076ae7564a06bc6c114cd227144d88301a8655b01df23967350ce762d2", - "size": 1121295 + "path": "en/api/beta/vaults/delete.md", + "sha256": "3220a53caebb38c1940766e7ccaf839655b165e57584e3244864c2379cefc674", + "size": 1617 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/models", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/archive", "status": "success", - "path": "en/api/typescript/beta/models.md", - "sha256": "9905ee8d39832b6e3976b13ae13e88c8b8d8522a47a8a68de2bc12bfd453b441", - "size": 23734 + "path": "en/api/beta/vaults/archive.md", + "sha256": "f316d1ee0a97b54ac5e268838ef7d9ea8299bc80007c30e6add02da5ed3c7e39", + "size": 2003 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/models/list", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/credentials", "status": "success", - "path": "en/api/typescript/beta/models/list.md", - "sha256": "b6f8b02fc55828aecb12a1620156fe414e4d056f7f71e1944fc1943293be013c", - "size": 6614 + "path": "en/api/beta/vaults/credentials.md", + "sha256": "a79a230c33f214ff9d198ba54c4adfb429c8b21cc4b4f04bd9039e83c07495e0", + "size": 45918 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/credentials/create", "status": "success", - "path": "en/api/typescript/beta/models/retrieve.md", - "sha256": "2d57558c0e24310642126a93b98a69d882c41a4ad2fc3e54ebcfe3662d65d3b9", - "size": 6156 + "path": "en/api/beta/vaults/credentials/create.md", + "sha256": "710ea3fee0d39d6f9f7fe675ff8feb582f57b03631cd68b4fc4894c857bfc5b7", + "size": 7410 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/credentials/list", "status": "success", - "path": "en/api/typescript/beta/messages.md", - "sha256": "b57cdb575db97c6742afb9a13abf83ad4bac7c0b8520a24fdb04fd4d584207af", - "size": 1041514 + "path": "en/api/beta/vaults/credentials/list.md", + "sha256": "29b511f2b247f3b9557fdaed6d753b060341e2edfe83efaa366e5fb4f74d685f", + "size": 4740 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/create", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/credentials/retrieve", "status": "success", - "path": "en/api/typescript/beta/messages/create.md", - "sha256": "6d036ecd707125b395f6689b883842e19bfab103b17b979ec9f3d701e1898a0c", - "size": 152363 + "path": "en/api/beta/vaults/credentials/retrieve.md", + "sha256": "d58e07f6a042f61efde661ca1361e4b9f6b0b08c65057597786d4d4e6fdd29ce", + "size": 4451 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/credentials/update", "status": "success", - "path": "en/api/typescript/beta/messages/count_tokens.md", - "sha256": "29b8c2aae9b19b725048ef31888264d9a0bde0fb891191691b8dd2326cc1628a", - "size": 114782 + "path": "en/api/beta/vaults/credentials/update.md", + "sha256": "72971c1d211e067e4b3397ebc1f041d1c7392e1e112786e66ed6343fe09d5726", + "size": 6842 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/credentials/delete", "status": "success", - "path": "en/api/typescript/beta/messages/batches.md", - "sha256": "cc041e336ae57820894a42eb6c73f7234f4523b65346aa09c942e5f274512c7f", - "size": 288425 + "path": "en/api/beta/vaults/credentials/delete.md", + "sha256": "bdb7754b939d830edd0d0df5da5cbf72b754fc492fdc4a99c08c9b92f043bda2", + "size": 1741 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/beta/vaults/credentials/archive", "status": "success", - "path": "en/api/typescript/beta/messages/batches/create.md", - "sha256": "6a5c85e1e8035892ef7961539f97d493e91f4e9050bd1ad59dd2ea651e3c3178", - "size": 131318 + "path": "en/api/beta/vaults/credentials/archive.md", + "sha256": "97f09ef5b642332be4f6888dbf8e39a2c21951cf3a39c9c648390705d63ae72b", + "size": 4485 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/beta/files", "status": "success", - "path": "en/api/typescript/beta/messages/batches/retrieve.md", - "sha256": "69074a74be215b9ea4939f2db29d9317f09a0fa662a939f7b8ca7ed538bf051f", - "size": 4809 + "path": "en/api/beta/files.md", + "sha256": "a19b6aa7f5c48f1bc9687922bc94940aee342c0469d55d4f298c052bc005010c", + "size": 12218 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/beta/files/upload", "status": "success", - "path": "en/api/typescript/beta/messages/batches/list.md", - "sha256": "e90ac1c58cd82ae51d94d83ceb69bfc15829102218e0a86c5c135a0911f7ac55", - "size": 5130 + "path": "en/api/beta/files/upload.md", + "sha256": "63027d4b8d10f7fb7919d98aaa9194e2a462bcb54b478e7c7ff6128f066f613a", + "size": 2318 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/beta/files/list", "status": "success", - "path": "en/api/typescript/beta/messages/batches/cancel.md", - "sha256": "7bab1ae3086de09d28c49c87ef3f7becf28d19d3fbdd4b74686598ec9bfe70bf", - "size": 5117 + "path": "en/api/beta/files/list.md", + "sha256": "5ac9caa7357edffd63684b2eea7685483da5f0df9c4704f4b27ec6409ebc36a6", + "size": 3066 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/beta/files/download", "status": "success", - "path": "en/api/typescript/beta/messages/batches/delete.md", - "sha256": "c011dad0e5718f22226631962b4e8a10b629c008ed51d73de372580c4fcf256b", - "size": 2271 + "path": "en/api/beta/files/download.md", + "sha256": "6aa513b2e4bf4a9111bcd3ea3f0b5832565dc29c4615a5b57e5102abca18f14a", + "size": 1403 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/beta/files/retrieve_metadata", "status": "success", - "path": "en/api/typescript/beta/messages/batches/results.md", - "sha256": "cf6ffdc486238b6a25bedd1f9f60739082b4cd4ab2fc526eee7ac8d45ebf53ee", - "size": 36825 + "path": "en/api/beta/files/retrieve_metadata.md", + "sha256": "067cd0c02456befb6641ad787d6a2b217961604753b5fd31fd6d41e3b0084138", + "size": 2338 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/files", + "url": "https://platform.claude.com/docs/en/api/beta/files/delete", "status": "success", - "path": "en/api/typescript/beta/files.md", - "sha256": "bd27307c62fa1f6ce78b044a71c9ff4d83427dc08a827e34366f5b256776f756", - "size": 11547 + "path": "en/api/beta/files/delete.md", + "sha256": "6a36344e16917bcd64dc7050f598b35c10638e5778badc5bb2bf1ece216b3c60", + "size": 1645 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/files/upload", + "url": "https://platform.claude.com/docs/en/api/beta/skills", "status": "success", - "path": "en/api/typescript/beta/files/upload.md", - "sha256": "d4e4090121a934a5104667093bdb7fca8cfb9ee2c25166cea5949ed773edd857", - "size": 2243 + "path": "en/api/beta/skills.md", + "sha256": "e5d9a490cd547eb60824c8189f78656ea1ec46c53ee66cc77f8e43bdda03b164", + "size": 26058 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/files/list", + "url": "https://platform.claude.com/docs/en/api/beta/skills/create", "status": "success", - "path": "en/api/typescript/beta/files/list.md", - "sha256": "8f3864a0d343bb18bd3c3fc64500b30319cdff06dab1c77eb599010e89af8fee", - "size": 2657 + "path": "en/api/beta/skills/create.md", + "sha256": "dfe2d047e2aa964d922286f2cffd2ff9b074a9ec7a77c2253a2a9471a021cfaa", + "size": 2164 + }, + { + "url": "https://platform.claude.com/docs/en/api/beta/skills/list", + "status": "success", + "path": "en/api/beta/skills/list.md", + "sha256": "1fe2a2121a7ad30a70d5f2aee123c2ba2ea9dd1fdaf70c8301b61d341d3fab3b", + "size": 3196 + }, + { + "url": "https://platform.claude.com/docs/en/api/beta/skills/retrieve", + "status": "success", + "path": "en/api/beta/skills/retrieve.md", + "sha256": "e9bfff9dc5ee45b86267919efbd5b38061df93e8a43f9b43b1a37b16e34b849f", + "size": 2302 + }, + { + "url": "https://platform.claude.com/docs/en/api/beta/skills/delete", + "status": "success", + "path": "en/api/beta/skills/delete.md", + "sha256": "f1a5824d31df5fdf6ec6955258c5e94f6bbcd235877060d81c4a8f400e798407", + "size": 1686 + }, + { + "url": "https://platform.claude.com/docs/en/api/beta/skills/versions", + "status": "success", + "path": "en/api/beta/skills/versions.md", + "sha256": "be37e633a5b303d0b03a3f7af6783fb7fbe38d497eafd2cf62758aa21ba18cc0", + "size": 13462 + }, + { + "url": "https://platform.claude.com/docs/en/api/beta/skills/versions/create", + "status": "success", + "path": "en/api/beta/skills/versions/create.md", + "sha256": "72cb19c3f55ea8918bd082242bbd01dacc5f8248887f65c00a402416f9afc9ca", + "size": 2425 + }, + { + "url": "https://platform.claude.com/docs/en/api/beta/skills/versions/list", + "status": "success", + "path": "en/api/beta/skills/versions/list.md", + "sha256": "f045641bd1322f002396e5e2fc3a3a3c7f31094989f13c563ae384698d2988d5", + "size": 2992 + }, + { + "url": "https://platform.claude.com/docs/en/api/beta/skills/versions/retrieve", + "status": "success", + "path": "en/api/beta/skills/versions/retrieve.md", + "sha256": "6b6566b9505fe9b04dee1b4179d3b2464bbda2c69b8bc76ee56c1fac9e604a15", + "size": 2570 + }, + { + "url": "https://platform.claude.com/docs/en/api/beta/skills/versions/delete", + "status": "success", + "path": "en/api/beta/skills/versions/delete.md", + "sha256": "6abee4aa497897e6ac2e0c34f758843dce2a3c0cc9c23b95cea8d3e0daa1ae49", + "size": 1920 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/completions", + "status": "success", + "path": "en/api/typescript/completions.md", + "sha256": "f403009e1087c651b4f9405f5eb6b4c50f6d8d8b1df9e3ed6decc692d8a35d3e", + "size": 12489 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/completions/create", + "status": "success", + "path": "en/api/typescript/completions/create.md", + "sha256": "c0843117692cf677e917989ff82408676ec00c75fd59e8a70e1f3ac55902f421", + "size": 10014 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/messages", + "status": "success", + "path": "en/api/typescript/messages.md", + "sha256": "8dc219d1932037cc249a1127bb397b8ebb903a9f4299d4249feb1efddffc3f42", + "size": 842040 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/messages/create", + "status": "success", + "path": "en/api/typescript/messages/create.md", + "sha256": "66250dc8e54c47a7438ffa5f0e448e073a5a66e258c963dea6c88179de73b538", + "size": 121316 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/messages/count_tokens", + "status": "success", + "path": "en/api/typescript/messages/count_tokens.md", + "sha256": "57c715746b7bbef937a9b02d6329aa65e5012c29990a3ca358cab60166f7d5dc", + "size": 92991 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches", + "status": "success", + "path": "en/api/typescript/messages/batches.md", + "sha256": "fd63aaf7d2ca0f16aaf30f6da92013c8713fc1c2252d87414e8d150c3aa31ee0", + "size": 224801 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches/create", + "status": "success", + "path": "en/api/typescript/messages/batches/create.md", + "sha256": "89e68fe2bf621138738929fc221e4b66058000f0fc8a7fc4c4d3f26bb4734a1b", + "size": 107448 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches/retrieve", + "status": "success", + "path": "en/api/typescript/messages/batches/retrieve.md", + "sha256": "a46e305636c3469ef0de4772ddbf94a7047b36ff62dde8ea939b0d65e8f43634", + "size": 3637 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches/list", + "status": "success", + "path": "en/api/typescript/messages/batches/list.md", + "sha256": "f08b6a4ebd48b6f1b3867e11374ac83f89ab802efbf4cf1ed05b42f9d0abbd8c", + "size": 3964 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches/cancel", + "status": "success", + "path": "en/api/typescript/messages/batches/cancel.md", + "sha256": "a9b39fec2334f9cf14a3a68dff436006b889ecaf9b3f5b4d9252276422e8af90", + "size": 3949 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches/delete", + "status": "success", + "path": "en/api/typescript/messages/batches/delete.md", + "sha256": "119dfb75f469b9c2cf2b1c924b24d6b43af84ee6866f37933da5eaaad9da2159", + "size": 1107 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/messages/batches/results", + "status": "success", + "path": "en/api/typescript/messages/batches/results.md", + "sha256": "85c03089e3f37816a8a7ba328a7ee4b79f4dcd3cebeebdf4deb3eda172744cf7", + "size": 26961 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/models", + "status": "success", + "path": "en/api/typescript/models.md", + "sha256": "f29ada5ac94221d598d188cc44d9bcd50f1dbe308e3f11362f205a9966f58427", + "size": 23179 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/models/list", + "status": "success", + "path": "en/api/typescript/models/list.md", + "sha256": "58815286613b06fcc21829fa4485aa4f49d2dac1ff8876dde5321825e5be0602", + "size": 6470 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/models/retrieve", + "status": "success", + "path": "en/api/typescript/models/retrieve.md", + "sha256": "bcaa5e76f21bd7618e0c2f75afe7655421a743f860164bede2fe104e789c3bfa", + "size": 6012 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta", + "status": "success", + "path": "en/api/typescript/beta.md", + "sha256": "5ad61062e7d5756952c32685565368f7f46d1ff3365050c192525e263181d4fc", + "size": 1641080 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/models", + "status": "success", + "path": "en/api/typescript/beta/models.md", + "sha256": "ed93599e4419cabd377fb297bb70a2fc56c9aeebb1138eb7df6cf21745e2526f", + "size": 23658 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/models/list", + "status": "success", + "path": "en/api/typescript/beta/models/list.md", + "sha256": "5041520be905414b72ac4c2e757fee104718cf24843ac2d8a4283bfb603e843c", + "size": 6576 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/models/retrieve", + "status": "success", + "path": "en/api/typescript/beta/models/retrieve.md", + "sha256": "4e9800cce34b51113467a3e1e70ae538e644e54634744ca6e67b5d9e151e7973", + "size": 6118 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages", + "status": "success", + "path": "en/api/typescript/beta/messages.md", + "sha256": "6354b9f0ed7bcfdb1ab3304d9365223eecb162f9446448dabc1e1a499af3fcb3", + "size": 1042215 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/create", + "status": "success", + "path": "en/api/typescript/beta/messages/create.md", + "sha256": "e89e85896e598ee8c1a00a6fce7dfc9c39cbfe52ad2be86fe170ddb9ee316800", + "size": 152384 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/count_tokens", + "status": "success", + "path": "en/api/typescript/beta/messages/count_tokens.md", + "sha256": "2a1c93c1de263230bf45cd2db469aca8dca4e842da88faf066269caed70caff7", + "size": 114867 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches", + "status": "success", + "path": "en/api/typescript/beta/messages/batches.md", + "sha256": "d779914278ff70be419b77d1ba01233fa3a9ce9014bbf7134bda8bcd4daf5c0e", + "size": 288657 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches/create", + "status": "success", + "path": "en/api/typescript/beta/messages/batches/create.md", + "sha256": "e8b0c169f446ab5407b71f5b6add39555f65fd0a682ac09ee3f32707baf6f847", + "size": 131236 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches/retrieve", + "status": "success", + "path": "en/api/typescript/beta/messages/batches/retrieve.md", + "sha256": "d2374bc003c6e7d359511df96cffb867217d77c515bb9f396b3573bcdd20e089", + "size": 4771 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches/list", + "status": "success", + "path": "en/api/typescript/beta/messages/batches/list.md", + "sha256": "2f7016be35799e0388a3fdddc596f410cef7f6bb8fb00a055b66851e8ade2b3a", + "size": 5092 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches/cancel", + "status": "success", + "path": "en/api/typescript/beta/messages/batches/cancel.md", + "sha256": "3b31ca85276d51bc66ac0f18b81b60b8e56208890b581df06160cc4d13dcf8a3", + "size": 5079 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches/delete", + "status": "success", + "path": "en/api/typescript/beta/messages/batches/delete.md", + "sha256": "e507a5c7b33dca4330a2972d6d2a8f7faa05859a31e7e44483c3ff0a1b7e8cbf", + "size": 2233 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/messages/batches/results", + "status": "success", + "path": "en/api/typescript/beta/messages/batches/results.md", + "sha256": "444d5193a7874e3b1cf6f5022df1d5f641401d77cfe38b46a48e612134df1168", + "size": 36916 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/agents", + "status": "success", + "path": "en/api/typescript/beta/agents.md", + "sha256": "65e76f23fe29b61188bd075a9beb98199f2584eb7ab90b29a28b491c6ed65ab5", + "size": 99501 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/agents/create", + "status": "success", + "path": "en/api/typescript/beta/agents/create.md", + "sha256": "9bdd507dc0e3de6ca816302f9162428ea9256cc44105d628570beff9a3ea6653", + "size": 18248 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/agents/list", + "status": "success", + "path": "en/api/typescript/beta/agents/list.md", + "sha256": "5770324510714aaecc65aedb6d77431a3f1ba64e9087f345a822f9f36533bdaa", + "size": 8681 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/agents/retrieve", + "status": "success", + "path": "en/api/typescript/beta/agents/retrieve.md", + "sha256": "21af9c198398c99e43cb9522dfa85c51d17fbb2bc7f4b80b5a76bd574b2d0919", + "size": 8335 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/agents/update", + "status": "success", + "path": "en/api/typescript/beta/agents/update.md", + "sha256": "e26de92f5642ac1b05d7d21b283ace1f921fd43a6a568003ae99419be92e833b", + "size": 18939 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/agents/archive", + "status": "success", + "path": "en/api/typescript/beta/agents/archive.md", + "sha256": "1082505965cef2daeaf6fe4b6f653f6306227cfac4fab3a0b92c932256e0708c", + "size": 8205 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/agents/versions", + "status": "success", + "path": "en/api/typescript/beta/agents/versions.md", + "sha256": "cfa60837e1107cd1e603a30dc394dc6497c639ba007084d588db2a3c87458f3c", + "size": 8475 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/agents/versions/list", + "status": "success", + "path": "en/api/typescript/beta/agents/versions/list.md", + "sha256": "dafd0300ddae54013e03236a5de68fc9af16bc3c4d20641e10f4c32d2b988547", + "size": 8463 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/environments", + "status": "success", + "path": "en/api/typescript/beta/environments.md", + "sha256": "724e72f79e84718881c67e0704daabb8e72441a72682fa716df017686ae7ee1e", + "size": 36583 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/environments/create", + "status": "success", + "path": "en/api/typescript/beta/environments/create.md", + "sha256": "dac51ea3a6d58ce6f2f50d869debe0138689330fdd7b2e0bf2abec4a1a77fb54", + "size": 6498 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/environments/list", + "status": "success", + "path": "en/api/typescript/beta/environments/list.md", + "sha256": "114dfb585cac247af36624eb0444f3693b9f1dcb02d607ef0738161dc93ea335", + "size": 4317 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/environments/retrieve", + "status": "success", + "path": "en/api/typescript/beta/environments/retrieve.md", + "sha256": "bff2f69a64f761a10de23f36fff8375cdf37f57b7bb0cdb587ee2eaabbe507dd", + "size": 4011 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/environments/update", + "status": "success", + "path": "en/api/typescript/beta/environments/update.md", + "sha256": "e0c1046e4a52ad5b0c1d802754ac930a6edf6be54cb5069d154b43e8683be906", + "size": 6613 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/environments/delete", + "status": "success", + "path": "en/api/typescript/beta/environments/delete.md", + "sha256": "69b0175ff4751408ab2c89d463a5583aeb6b510e1ca305e8c8aebfd028c6d80f", + "size": 1983 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/environments/archive", + "status": "success", + "path": "en/api/typescript/beta/environments/archive.md", + "sha256": "f217661d48a5ba4860d82de846684f7beec45d9aa8e06e30da84c1954b846e53", + "size": 4067 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions", + "status": "success", + "path": "en/api/typescript/beta/sessions.md", + "sha256": "f70256aec22e036683b31c33e4562a0429bc888768ecc65c83cad56e62c9f803", + "size": 333460 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/create", + "status": "success", + "path": "en/api/typescript/beta/sessions/create.md", + "sha256": "a0c33aadbc3efaa2c905a634847561acb2023ab0db02a8e7dba5ef9dcb9aa5a8", + "size": 13791 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/list", + "status": "success", + "path": "en/api/typescript/beta/sessions/list.md", + "sha256": "7e3d739b801bcc8ce4451d65e3051b5d64d2a8c2991e8c837983507d5c3d5ef5", + "size": 12218 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/retrieve", + "status": "success", + "path": "en/api/typescript/beta/sessions/retrieve.md", + "sha256": "92edf2b9f0c3fff2ceee8661501f0b1312aae4acecad000444f5817a6f2e82f8", + "size": 11161 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/update", + "status": "success", + "path": "en/api/typescript/beta/sessions/update.md", + "sha256": "dd9d02cdc3ecdee0823c9aec6219094764a1dc955520a8772a62cfd50521ae02", + "size": 11598 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/delete", + "status": "success", + "path": "en/api/typescript/beta/sessions/delete.md", + "sha256": "2b740c1523175f1859c8cd7674d779e68e1449ea1fb4feb9ff0c2a226812f0b9", + "size": 1864 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/archive", + "status": "success", + "path": "en/api/typescript/beta/sessions/archive.md", + "sha256": "04cbf88dac7924f731fae58d1f995afb926ba9b0f0c0d8f53b0eace09bf94b3b", + "size": 11169 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/events", + "status": "success", + "path": "en/api/typescript/beta/sessions/events.md", + "sha256": "e1d74bfa7fc224ac9c93fe30082f44df89959f8ac59f046d0764b9e2ec27b037", + "size": 233527 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/events/list", + "status": "success", + "path": "en/api/typescript/beta/sessions/events/list.md", + "sha256": "4d922402c582e5d26af53e75545bc5365427fc2e3fbe99dd669330de290d98b6", + "size": 35765 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/events/send", + "status": "success", + "path": "en/api/typescript/beta/sessions/events/send.md", + "sha256": "2bc5d226fdcd86a562a7bb8c0330b165ba72f8ccebd58c59b7f6e356efbc28d5", + "size": 20002 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/events/stream", + "status": "success", + "path": "en/api/typescript/beta/sessions/events/stream.md", + "sha256": "41f50357bb5336b66fc874793160c4e0297a3429d39db3c028dbaa76fa221254", + "size": 35440 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/resources", + "status": "success", + "path": "en/api/typescript/beta/sessions/resources.md", + "sha256": "fb6f493e0d9a94ff7843a01b0279f3e68ef3abe2ff35350d04fbf07a76f7bf39", + "size": 18491 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/resources/add", + "status": "success", + "path": "en/api/typescript/beta/sessions/resources/add.md", + "sha256": "c62345617466ad169e69db639e904c9d22d994c35d4fa0d797b16d8ccff4e21e", + "size": 2292 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/resources/list", + "status": "success", + "path": "en/api/typescript/beta/sessions/resources/list.md", + "sha256": "045ef825efa6416486fa20a2a52dd4abc66cc8724d3d845ecd84cad2fb0717b7", + "size": 3154 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/resources/retrieve", + "status": "success", + "path": "en/api/typescript/beta/sessions/resources/retrieve.md", + "sha256": "483aea3847dac5f708f964dccf92551c228d6f4a5f5b292a9a38419d561b7d34", + "size": 2975 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/resources/update", + "status": "success", + "path": "en/api/typescript/beta/sessions/resources/update.md", + "sha256": "19dc03fb4229e9f4ca7390363fd6b946a663bec44c39e15770aff2e6e12528c6", + "size": 3169 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/sessions/resources/delete", + "status": "success", + "path": "en/api/typescript/beta/sessions/resources/delete.md", + "sha256": "8cea447c0c2eedd5e893f5a514eb7ba0356745255133fa1b83bd525d40528b8a", + "size": 2077 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults", + "status": "success", + "path": "en/api/typescript/beta/vaults.md", + "sha256": "5591fee5d5addf73ad22e6b87088cba5cf66246233e7f072c2e7cea7d8487c0b", + "size": 60053 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/create", + "status": "success", + "path": "en/api/typescript/beta/vaults/create.md", + "sha256": "de6239277ae3fa842269db2ba315f491ed8decb0992d858a13ab48f5f8d2351e", + "size": 2364 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/list", + "status": "success", + "path": "en/api/typescript/beta/vaults/list.md", + "sha256": "6c85be214bb3bcb16db18d1126d516e98bdc0d86146d13dca63d9b5e9e2578df", + "size": 2501 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/retrieve", + "status": "success", + "path": "en/api/typescript/beta/vaults/retrieve.md", + "sha256": "90f930f2a109e868fae7c683c688d9e521771959794dc6f227d11fabf8c40285", + "size": 2192 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/update", + "status": "success", + "path": "en/api/typescript/beta/vaults/update.md", + "sha256": "b98a4ae62f4b2572b5af7aa60bed4f5ba6e15465fece5f4175edd213bf80aedf", + "size": 2490 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/delete", + "status": "success", + "path": "en/api/typescript/beta/vaults/delete.md", + "sha256": "c0bd58d9bbad30e00459177d08decd94f7170d37efe43fad052737cf627d1f46", + "size": 1851 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/archive", + "status": "success", + "path": "en/api/typescript/beta/vaults/archive.md", + "sha256": "78c2ac06c14c7254ebb78c62f3a70bff14db76581d6eb76f4abb703bd398162b", + "size": 2200 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/credentials", + "status": "success", + "path": "en/api/typescript/beta/vaults/credentials.md", + "sha256": "8eece22bd763c7d6d9183cb346f97da9765e79238cd0e2c90a9707ebae13eaa0", + "size": 45613 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/credentials/create", + "status": "success", + "path": "en/api/typescript/beta/vaults/credentials/create.md", + "sha256": "e46bf7a25b40cbe167f60e40875bd1f2000522470bca6775648887949c3d0f7e", + "size": 7380 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/credentials/list", + "status": "success", + "path": "en/api/typescript/beta/vaults/credentials/list.md", + "sha256": "25a3f3cbb515484563e1135c4d82c86b610fd211ae8010b64050ae555ec35c7b", + "size": 4914 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/credentials/retrieve", + "status": "success", + "path": "en/api/typescript/beta/vaults/credentials/retrieve.md", + "sha256": "713fe93bb78a355ae42c13c372b35b5ddf4e0c49ad1c947fbec13c761e8d37b6", + "size": 4666 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/credentials/update", + "status": "success", + "path": "en/api/typescript/beta/vaults/credentials/update.md", + "sha256": "0c0c477b22d4724cfd34417b20b25769aafcca2791220fbe50b700dfc4fd29e1", + "size": 6934 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/credentials/delete", + "status": "success", + "path": "en/api/typescript/beta/vaults/credentials/delete.md", + "sha256": "62cc46e1f8f7870392f7faa93074595e87a9e19191ca8a27b67701ce096304d5", + "size": 2107 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/vaults/credentials/archive", + "status": "success", + "path": "en/api/typescript/beta/vaults/credentials/archive.md", + "sha256": "7260029c69168fce99371bd91b3b18782c8158e3e63e96a6ee38229946104247", + "size": 4674 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/files", + "status": "success", + "path": "en/api/typescript/beta/files.md", + "sha256": "c90167589627b8ef73680dcdab64ba49a40532973355811d12845bd2c20ab4fd", + "size": 12921 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/files/upload", + "status": "success", + "path": "en/api/typescript/beta/files/upload.md", + "sha256": "fd79f23e26b25b651531bd24a46140f9ebb585c98994fe6b175d98fbbf829f82", + "size": 2510 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/files/list", + "status": "success", + "path": "en/api/typescript/beta/files/list.md", + "sha256": "61df7a0460e73190971df373091ade8b37d670b30fedea75f333937247cfa355", + "size": 3064 }, { "url": "https://platform.claude.com/docs/en/api/typescript/beta/files/download", "status": "success", - "path": "en/api/typescript/beta/files/download.md", - "sha256": "17fe55152e649aa40107afafd79c319c59fadc05fe44c6aa0346f09ef5e13da3", - "size": 1731 + "path": "en/api/typescript/beta/files/download.md", + "sha256": "955c90ec69b3c8a8deeb076dd1bc45181538ebbc6b535126cb18fbc9014d8298", + "size": 1693 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/files/retrieve_metadata", + "status": "success", + "path": "en/api/typescript/beta/files/retrieve_metadata.md", + "sha256": "2574ed26ec0997f79b4ad058317071eec3a735c02e5f4c057b662ab8ed113e1b", + "size": 2520 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/files/delete", + "status": "success", + "path": "en/api/typescript/beta/files/delete.md", + "sha256": "26fb66e08105df117d9e7900209d3aa5e2c4490c9241f3671702d143e94e1b07", + "size": 1793 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills", + "status": "success", + "path": "en/api/typescript/beta/skills.md", + "sha256": "35b51c8defe2f2b6e17e14eb48de73c8e693184b8a85ad5e4b1d769964fa909e", + "size": 28012 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/create", + "status": "success", + "path": "en/api/typescript/beta/skills/create.md", + "sha256": "d713c37df22354ac838a30f415ca8d4ea03910039a3b85b3c3d9e518337adef3", + "size": 2829 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/list", + "status": "success", + "path": "en/api/typescript/beta/skills/list.md", + "sha256": "4167f29645351507a6b864179c96a214c69fdb7174b933ebb7a25c150f63521f", + "size": 3106 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/retrieve", + "status": "success", + "path": "en/api/typescript/beta/skills/retrieve.md", + "sha256": "c75a79d740e0927c27a5766d32d6d3b5ce9b9bfb227af0b8e0718db07a606c6d", + "size": 2592 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/delete", + "status": "success", + "path": "en/api/typescript/beta/skills/delete.md", + "sha256": "3cf8d64e3ecdbe91f4d2c50d275d22343ae2c8c8a93cb4e714f436136b065cdd", + "size": 1904 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/versions", + "status": "success", + "path": "en/api/typescript/beta/skills/versions.md", + "sha256": "dc1c389b70537a6173cf7be4b0af3d30d024fcbaf071857871b536282d8fc3c2", + "size": 14466 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/versions/create", + "status": "success", + "path": "en/api/typescript/beta/skills/versions/create.md", + "sha256": "fcce9f941cddc35c9303bb8ec124442fbcabd9c8b99c01299912267b451b621e", + "size": 2919 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/versions/list", + "status": "success", + "path": "en/api/typescript/beta/skills/versions/list.md", + "sha256": "c1c2843ac4738cce415c99200a4b4e686368ca34afee5733446fef8ef9818edb", + "size": 3037 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/versions/retrieve", + "status": "success", + "path": "en/api/typescript/beta/skills/versions/retrieve.md", + "sha256": "1bfd800865c924d3436a7a482718d0131c6b37afa8f2e804e8ddc4f0906d9cd7", + "size": 2917 + }, + { + "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/versions/delete", + "status": "success", + "path": "en/api/typescript/beta/skills/versions/delete.md", + "sha256": "c3b888b5a2a5b4ed2b0fb86702832c40c6f0c37193bc84fca5568acd234b6ba9", + "size": 2207 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/completions", + "status": "success", + "path": "en/api/python/completions.md", + "sha256": "6b3a7835c6c4a0fcae3a534ba9dc4820c8a4434c4b1e17ff244820d6e6585e5e", + "size": 16063 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/completions/create", + "status": "success", + "path": "en/api/python/completions/create.md", + "sha256": "97859080eb4c710cb707b5c33b071f338d08ad98e2db987ea8b4118312434fff", + "size": 11967 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/messages", + "status": "success", + "path": "en/api/python/messages.md", + "sha256": "a5d3344c3d1f269a80cdc9e51c1cb7c37bc824b233f35bea038ed64c3ea31f7e", + "size": 870113 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/messages/create", + "status": "success", + "path": "en/api/python/messages/create.md", + "sha256": "12199547486fdec68a0d00e0d52cb460131fe2314e259ca221470eefd16412ec", + "size": 119761 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/messages/count_tokens", + "status": "success", + "path": "en/api/python/messages/count_tokens.md", + "sha256": "327daaeeff0dde9b3cd4609e45ba7a22feaae3b89f2a74f203e853a1a220c70a", + "size": 94123 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/messages/batches", + "status": "success", + "path": "en/api/python/messages/batches.md", + "sha256": "f250ea9593bfaa4947582a1d5da3b8933f0f83cdef7f6f40392dc796aa2ac2fa", + "size": 234472 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/messages/batches/create", + "status": "success", + "path": "en/api/python/messages/batches/create.md", + "sha256": "29116c88d473863e8631e0aca01c427caae94034f392a874adb90007bd13481a", + "size": 108696 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/messages/batches/retrieve", + "status": "success", + "path": "en/api/python/messages/batches/retrieve.md", + "sha256": "0d277d480739f911ab4376e600949bf82f01633bc39154d07f28846a77d72010", + "size": 3609 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/messages/batches/list", + "status": "success", + "path": "en/api/python/messages/batches/list.md", + "sha256": "6de85ce7f5d2a44c1d8e815a67e552cc88ce58aea737221c67e614905d46ebc9", + "size": 3857 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/messages/batches/cancel", + "status": "success", + "path": "en/api/python/messages/batches/cancel.md", + "sha256": "17492c90948f23ad1f8ad17d33ab20e32d1bf14c9b65da102827a8e31ce7f79c", + "size": 3921 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/messages/batches/delete", + "status": "success", + "path": "en/api/python/messages/batches/delete.md", + "sha256": "74cd4bbe006b91b26d57aac7a654f489294abe32b24f440a8465c45cb3977acf", + "size": 1070 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/messages/batches/results", + "status": "success", + "path": "en/api/python/messages/batches/results.md", + "sha256": "722094a88d1c1376165d1ea96c8583be6135bf569f641fa20e3d6a53a80c2c94", + "size": 29053 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/models", + "status": "success", + "path": "en/api/python/models.md", + "sha256": "2074d6a451e9d06ae504b423325e328e93fd321aa69f7713784c7155d8e9c270", + "size": 22739 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/models/list", + "status": "success", + "path": "en/api/python/models/list.md", + "sha256": "05a3303e8c28d6077d0eca81e80edff17aadc5cdae6abda58da922e48d2791a0", + "size": 6219 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/models/retrieve", + "status": "success", + "path": "en/api/python/models/retrieve.md", + "sha256": "cfbf64fbc4cddf8b65cf99bef2aae188dc7401671611ae3cafa09ba01a808204", + "size": 5864 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta", + "status": "success", + "path": "en/api/python/beta.md", + "sha256": "c7b88ed780f715cb3f5425f60db620ffa14a4261d60ebea553b6d5dfb837ef93", + "size": 1665959 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/models", + "status": "success", + "path": "en/api/python/beta/models.md", + "sha256": "3e1900e00573a02e3433aef701c97a9ea3d1236983145a961b2227649d2cdb10", + "size": 23212 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/models/list", + "status": "success", + "path": "en/api/python/beta/models/list.md", + "sha256": "fa6be151678b3cc4e4ab27126d54fd792096d8a88e8cdecec292e8056dd29688", + "size": 6317 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/models/retrieve", + "status": "success", + "path": "en/api/python/beta/models/retrieve.md", + "sha256": "00c56eb0381fd7aabea748a91062064e2eead43fb4dee2ef6d90d27b9a7cdb51", + "size": 5972 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/messages", + "status": "success", + "path": "en/api/python/beta/messages.md", + "sha256": "f90d457bd9c83a718d34613d8d689b268adbd48a2e302475171d95e7c692e7c6", + "size": 1066533 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/messages/create", + "status": "success", + "path": "en/api/python/beta/messages/create.md", + "sha256": "fb1fd1ea8125113c43295ddf205227f978b22903dd076764d4c82b485e07d5da", + "size": 149285 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/messages/count_tokens", + "status": "success", + "path": "en/api/python/beta/messages/count_tokens.md", + "sha256": "6a249047842cb0816b8a3799a0bb7b9b533043ee445f330c42e0bf90fa8e9da7", + "size": 115458 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches", + "status": "success", + "path": "en/api/python/beta/messages/batches.md", + "sha256": "c45130e0ab42b9876a54679c481d8497bd8732cf0d867ac95f00610c960a8311", + "size": 297760 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches/create", + "status": "success", + "path": "en/api/python/beta/messages/batches/create.md", + "sha256": "264ab08bf19919b45cfe130b79e14b7a046e91b79b93b355171ea509d056b633", + "size": 132126 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches/retrieve", + "status": "success", + "path": "en/api/python/beta/messages/batches/retrieve.md", + "sha256": "8a7b091ee014b8ae25f42817ba0e7aab03d06cda2d6a55c0430e79aa8476733f", + "size": 4689 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches/list", + "status": "success", + "path": "en/api/python/beta/messages/batches/list.md", + "sha256": "7f8aef7f0b4c12930f46006c813d6328c92e2b38e9310d539a573900bfadffe3", + "size": 4881 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches/cancel", + "status": "success", + "path": "en/api/python/beta/messages/batches/cancel.md", + "sha256": "12caabd93ba49bff32bb2bb0ece4f22133d0cadf464c978dc0fe7fdea7157aa5", + "size": 4999 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches/delete", + "status": "success", + "path": "en/api/python/beta/messages/batches/delete.md", + "sha256": "a36da88e8710e69b1f397908db7a2c932f8a81bce75e25841b5e6ba7b9faed07", + "size": 2144 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches/results", + "status": "success", + "path": "en/api/python/beta/messages/batches/results.md", + "sha256": "c2a7fd2771aa253c0290d21ee091eb939079e38bfc5c7822fc549f9d30c1dad3", + "size": 38971 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/agents", + "status": "success", + "path": "en/api/python/beta/agents.md", + "sha256": "a23bdc8884d76d4a61a45fb35146ebc35439c0caef37f149fced1f8d1fdb5224", + "size": 108530 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/agents/create", + "status": "success", + "path": "en/api/python/beta/agents/create.md", + "sha256": "8a3419279870d8d9ca4d9f9fe2ba451069c2a5713b735517562fdf01cf777c21", + "size": 19895 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/agents/list", + "status": "success", + "path": "en/api/python/beta/agents/list.md", + "sha256": "5da0cf8921f30ffa5525fecbee01c717ab5380073fac549d8a4e49be9128d39c", + "size": 9214 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/agents/retrieve", + "status": "success", + "path": "en/api/python/beta/agents/retrieve.md", + "sha256": "bc0f8d5001f9a00b6b876c894e355e75b2cf1c2c3a7fe955a22c4f381f4b3a64", + "size": 8958 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/agents/update", + "status": "success", + "path": "en/api/python/beta/agents/update.md", + "sha256": "0495405e5d2eba78034930db48cb9f970f67c0dcba60ecbcd0196088b47a4f2f", + "size": 20568 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/agents/archive", + "status": "success", + "path": "en/api/python/beta/agents/archive.md", + "sha256": "85fc4e78eb7df5b3f376a86d33b2c922fef6c9f52482e8da742236b5ddc7ab73", + "size": 8854 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/agents/versions", + "status": "success", + "path": "en/api/python/beta/agents/versions.md", + "sha256": "d2d3846731546403863c1a4a785815f48f8d51a02daa177cdbec763f7857854c", + "size": 9008 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/agents/versions/list", + "status": "success", + "path": "en/api/python/beta/agents/versions/list.md", + "sha256": "3ab39f90a6b03c3e772af07902a7a14512bc15d7709fd5469a186d77a765e89b", + "size": 8996 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/environments", + "status": "success", + "path": "en/api/python/beta/environments.md", + "sha256": "0514b616b50cf20eae742e1ec77aa651a68d75f721fadf5d028b4d11db3a78f3", + "size": 35536 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/environments/create", + "status": "success", + "path": "en/api/python/beta/environments/create.md", + "sha256": "133af60984b5dc37127f5d70b6b634a828307a5c666b714f22eacd977d2f2e11", + "size": 6209 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/environments/list", + "status": "success", + "path": "en/api/python/beta/environments/list.md", + "sha256": "4486983945ff606726d06eb98af5f0bb0724ad9b4fb31f50c102537bef9e609a", + "size": 4065 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/environments/retrieve", + "status": "success", + "path": "en/api/python/beta/environments/retrieve.md", + "sha256": "46a9e49fa3ac7ab55625f876b0529390f25982b7a665f78c201943f0b5f31661", + "size": 3885 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/environments/update", + "status": "success", + "path": "en/api/python/beta/environments/update.md", + "sha256": "64841e00f9d5685bc41eed66d0d5990d23dc72b9c95d4d03f75c648f916c11aa", + "size": 6345 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/environments/delete", + "status": "success", + "path": "en/api/python/beta/environments/delete.md", + "sha256": "2b9a9ca06318191e82fdd7b249bb74f219fe6dac3a9dbbca8368d2e1de366c49", + "size": 1879 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/environments/archive", + "status": "success", + "path": "en/api/python/beta/environments/archive.md", + "sha256": "80c5ef072bdccfe36e91b2d7a363bfc11b452fc09b78df5d0698b9ffb92edc22", + "size": 3942 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions", + "status": "success", + "path": "en/api/python/beta/sessions.md", + "sha256": "c1f765b3070ff26cec3f968f228e6fa376ee1daba2580758cf6a755ea8f72ca2", + "size": 331265 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/create", + "status": "success", + "path": "en/api/python/beta/sessions/create.md", + "sha256": "ab53c992fc07b313e583036247239200160035c2aadaea7d9cf4b150e1140df9", + "size": 14265 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/list", + "status": "success", + "path": "en/api/python/beta/sessions/list.md", + "sha256": "b773165c17290e8b2bbd608a6b1b7609d47447e7ee5f5b4da90f5e97c37f9e10", + "size": 12823 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/retrieve", + "status": "success", + "path": "en/api/python/beta/sessions/retrieve.md", + "sha256": "84437d623582fd7a5c8733b4e0bdef56952540747cb779e30e92eafc9073ab15", + "size": 11892 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/update", + "status": "success", + "path": "en/api/python/beta/sessions/update.md", + "sha256": "6cce1a8ee3ed14fe8e0c9f7f0d623919fb59cbd539396ccfd27c728c7b097bb5", + "size": 12280 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/delete", + "status": "success", + "path": "en/api/python/beta/sessions/delete.md", + "sha256": "09e23f591f2892101f156ea87cad3458cdbe701643852de776b8bcd7b1c8bb0b", + "size": 1762 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/archive", + "status": "success", + "path": "en/api/python/beta/sessions/archive.md", + "sha256": "157b5e270fb4df29bdce7fd180769958b0e345ced1fa4b2be6bcfd5c12d2ea67", + "size": 11901 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/events", + "status": "success", + "path": "en/api/python/beta/sessions/events.md", + "sha256": "02332c7f743acdc85da940d3879537703a8bb6fd5c578d7d77ad6b07221872ad", + "size": 227757 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/events/list", + "status": "success", + "path": "en/api/python/beta/sessions/events/list.md", + "sha256": "c375173516aa383dbb21d3d88ee254bc8713bb648350fd462e6aaccd44e40cf4", + "size": 34832 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/events/send", + "status": "success", + "path": "en/api/python/beta/sessions/events/send.md", + "sha256": "4826469d317554bf7ad72f221f83897517090b5f1e5ca0239a7952fd945a08cd", + "size": 18990 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/events/stream", + "status": "success", + "path": "en/api/python/beta/sessions/events/stream.md", + "sha256": "0079331d024c098d128ec10a2e1e358c30e61509f20757342393cd36d24ddf43", + "size": 34528 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/resources", + "status": "success", + "path": "en/api/python/beta/sessions/resources.md", + "sha256": "6500a2f3bbdc3a53425a38b5929dd526a8137b8a68220b1a83d2b9e8d7ffe563", + "size": 17143 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/resources/add", + "status": "success", + "path": "en/api/python/beta/sessions/resources/add.md", + "sha256": "b3b9eff21d8279e28c8f3ef063355dbbf60bcfff6049353ef22be21baddf91a6", + "size": 2130 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/resources/list", + "status": "success", + "path": "en/api/python/beta/sessions/resources/list.md", + "sha256": "ce9d4baf7e3ff41ffcae224751441299add30e662e197589d7399f11cfae0b12", + "size": 2835 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/resources/retrieve", + "status": "success", + "path": "en/api/python/beta/sessions/resources/retrieve.md", + "sha256": "469b1acdb543a3f94ffb26d7c30f7d18174efdcf86c8d3be60912719503fd4e3", + "size": 2719 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/resources/update", + "status": "success", + "path": "en/api/python/beta/sessions/resources/update.md", + "sha256": "4704da90d8402ccd2a25939d719c05c94ce63f391ec0eae31138c5736d7925d9", + "size": 2897 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/sessions/resources/delete", + "status": "success", + "path": "en/api/python/beta/sessions/resources/delete.md", + "sha256": "1fd791cdc1ac13ddb38b777c524a4bdebbb9a3ca7a904cfb3d144bd258d8c841", + "size": 1913 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults", + "status": "success", + "path": "en/api/python/beta/vaults.md", + "sha256": "72a860098bb004bbb43e65b60974a1b397f65f1a95f4dcff6740baa9b629f390", + "size": 57021 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/create", + "status": "success", + "path": "en/api/python/beta/vaults/create.md", + "sha256": "d1b95b4ec1dc8d5750654f883a31425d9aee87d8b70287966a587637333efbd9", + "size": 2206 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/list", + "status": "success", + "path": "en/api/python/beta/vaults/list.md", + "sha256": "b7b4459c2049c862e80577dd5f06cdb5b6f6bbd06d15fc90b676ceb7e25b4a90", + "size": 2267 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/retrieve", + "status": "success", + "path": "en/api/python/beta/vaults/retrieve.md", + "sha256": "ec6239c8af0bef891281d9cac7d9b11260b69b4c691784bf3b4c1a219c69ccba", + "size": 2089 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/update", + "status": "success", + "path": "en/api/python/beta/vaults/update.md", + "sha256": "ba256e75bac2ae4a2c4339be8238ddccf414b58ae9f715a5183e7a940f7f5812", + "size": 2340 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/delete", + "status": "success", + "path": "en/api/python/beta/vaults/delete.md", + "sha256": "25fd3c304561a7991ab1563cbdaf69a4b494f3b9d585c64735a599d7c74ef40e", + "size": 1749 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/archive", + "status": "success", + "path": "en/api/python/beta/vaults/archive.md", + "sha256": "dfc14bc6230621e39071897a240da91e6e6f2503333d61f31dad876708874607", + "size": 2098 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/credentials", + "status": "success", + "path": "en/api/python/beta/vaults/credentials.md", + "sha256": "51e4700b4e6b0005c86659fece4205e9be3df1e903a9084fe39b546cfa294f64", + "size": 43398 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/credentials/create", + "status": "success", + "path": "en/api/python/beta/vaults/credentials/create.md", + "sha256": "92899a0a4ccfcf0358d89d344272b5bc685fd1afa0e3bee71273c6d357bafbf4", + "size": 6881 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/credentials/list", + "status": "success", + "path": "en/api/python/beta/vaults/credentials/list.md", + "sha256": "b9bc1e22ca4154f951f9725b77cd5a371dce2b64b0151c400a510b73ab5ba84c", + "size": 4558 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/credentials/retrieve", + "status": "success", + "path": "en/api/python/beta/vaults/credentials/retrieve.md", + "sha256": "cf76c0a46d6b34c3011d0ec92dd50dc041de3eaddac0a9628942221dae34e2c7", + "size": 4382 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/credentials/update", + "status": "success", + "path": "en/api/python/beta/vaults/credentials/update.md", + "sha256": "95a0773052516a37c297b2ad6a2be698cb33cb009bc2f74bb1080545146f1d49", + "size": 6468 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/credentials/delete", + "status": "success", + "path": "en/api/python/beta/vaults/credentials/delete.md", + "sha256": "e7b6843a6a73ea93a6b1090e829507a1865ffcf4820fa5337c5a3ab1af079ea4", + "size": 1943 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/vaults/credentials/archive", + "status": "success", + "path": "en/api/python/beta/vaults/credentials/archive.md", + "sha256": "a450afb4df0ac62bd348b27903247ad551c8575e59bd8930a2505801c962df3a", + "size": 4391 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/files", + "status": "success", + "path": "en/api/python/beta/files.md", + "sha256": "06b007afd4bbd87f3cfb676060ed9bd109782e5f0557183c7f9eaaf1ca150053", + "size": 12280 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/files/upload", + "status": "success", + "path": "en/api/python/beta/files/upload.md", + "sha256": "0a7dcc432eaccdc52e211870e47660902d250b2e5f62251ddc4d9f3357ee9798", + "size": 2355 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/files/list", + "status": "success", + "path": "en/api/python/beta/files/list.md", + "sha256": "015dffcad9b518709f34b568b3c4e19bc24b388f82792c11fbd8d02f29110cee", + "size": 2847 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/files/download", + "status": "success", + "path": "en/api/python/beta/files/download.md", + "sha256": "eb70712de91a9fd0946b28264518e16f5b7a23ed8323fd9dc3fb88871b077986", + "size": 1555 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/files/retrieve_metadata", + "status": "success", + "path": "en/api/python/beta/files/retrieve_metadata.md", + "sha256": "74473c8f6b7c653d06e780afbae803b900b0ffa2e40a02f689d09b271e9e023b", + "size": 2416 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/files/delete", + "status": "success", + "path": "en/api/python/beta/files/delete.md", + "sha256": "181b842c6950d0da30157a0a2cacfe00364c7eba4b1e13976ed7e767bfa99f8b", + "size": 1699 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/skills", + "status": "success", + "path": "en/api/python/beta/skills.md", + "sha256": "b9e09948929aeea5b010ebf520b013e1cf119928e439ce79dd532dcdd760d01c", + "size": 26524 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/skills/create", + "status": "success", + "path": "en/api/python/beta/skills/create.md", + "sha256": "ed3c448e455b31e73ebad3e923e96e65e7ece5c8faefa901eaaebf41f860aaf3", + "size": 2644 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/skills/list", + "status": "success", + "path": "en/api/python/beta/skills/list.md", + "sha256": "0c5aeaa79178cd8f7b034af13f2345638133e0ad75155aa1deee6cb97bd31662", + "size": 2839 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/skills/retrieve", + "status": "success", + "path": "en/api/python/beta/skills/retrieve.md", + "sha256": "d65894207987446f653a77e01e0e277d5cd44c88b340cbc66ac7e11eac44ec2f", + "size": 2464 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/skills/delete", + "status": "success", + "path": "en/api/python/beta/skills/delete.md", + "sha256": "ad7cc20bfa294647bd1bcc313de16b6813e39a85d349cf50546b07b13c4a8345", + "size": 1787 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/skills/versions", + "status": "success", + "path": "en/api/python/beta/skills/versions.md", + "sha256": "6b632e52122ca6ae7c1232224d0ac323d8e3b39f8ca70a9bf18548d3eb3ac2cf", + "size": 13682 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/skills/versions/create", + "status": "success", + "path": "en/api/python/beta/skills/versions/create.md", + "sha256": "915e9e44acb3540346086146b210cbff5427876a0ce11f7116282433f9a1e3ee", + "size": 2754 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/skills/versions/list", + "status": "success", + "path": "en/api/python/beta/skills/versions/list.md", + "sha256": "5b31be83fb2ba37c383f86454eab6cf7aa3cc0678df131d2ccacd2860babe1f1", + "size": 2786 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/skills/versions/retrieve", + "status": "success", + "path": "en/api/python/beta/skills/versions/retrieve.md", + "sha256": "f1d38f4c0e08ac475c2080f6b9fd48e0a723cc6ce19268d51ce34ed4856593cc", + "size": 2740 + }, + { + "url": "https://platform.claude.com/docs/en/api/python/beta/skills/versions/delete", + "status": "success", + "path": "en/api/python/beta/skills/versions/delete.md", + "sha256": "63c5d593e79efaf09ab40ac7ea17ec0136cb599942f7e671517d3de946ab3e4c", + "size": 2050 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/completions", + "status": "success", + "path": "en/api/java/completions.md", + "sha256": "db609b543e0d3cc145a523888d4a27888986739b8a93a2de39cf4a390f11e3bf", + "size": 10669 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/completions/create", + "status": "success", + "path": "en/api/java/completions/create.md", + "sha256": "5260e7c8d5115c3c29d4a16d49723079a7a72e37d27b260803466b6aa38028e5", + "size": 7983 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/messages", + "status": "success", + "path": "en/api/java/messages.md", + "sha256": "d7dae04be912753534fbc17ae675927ef565c63920b12ee08b2d8029014cc3ea", + "size": 920322 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/messages/create", + "status": "success", + "path": "en/api/java/messages/create.md", + "sha256": "d1d9baf83396373c03e16d546425198b69e49e984c5513ecdc8a748401390878", + "size": 122653 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/messages/count_tokens", + "status": "success", + "path": "en/api/java/messages/count_tokens.md", + "sha256": "68be31a803aeae8d38432220628051f2e65a94c8d0acc9dbf1ccfce04b9053cd", + "size": 96644 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/messages/batches", + "status": "success", + "path": "en/api/java/messages/batches.md", + "sha256": "2f4dd1b1dc5e08ff28f21e59a0894581f772fbf1284a84feb07e258af78419d4", + "size": 249013 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/messages/batches/create", + "status": "success", + "path": "en/api/java/messages/batches/create.md", + "sha256": "b2d63285ef581fab59d0e77f0b7c8ed8e6b86c9dd8effbc79dd202b334124f9f", + "size": 116668 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/messages/batches/retrieve", + "status": "success", + "path": "en/api/java/messages/batches/retrieve.md", + "sha256": "31ef3a6186ee81e8555c194abe39c78c319e393924dbe81bfe547c07af936232", + "size": 4046 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/messages/batches/list", + "status": "success", + "path": "en/api/java/messages/batches/list.md", + "sha256": "4c72371fbbc0ea3a4862f11ad8557966466adb6dd7385e02e0f6740e0bae0e0e", + "size": 4266 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/messages/batches/cancel", + "status": "success", + "path": "en/api/java/messages/batches/cancel.md", + "sha256": "1839e1ce519275e06452a811f7eb16628dba51fee26deb770677aa8894b7a5b3", + "size": 4350 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/messages/batches/delete", + "status": "success", + "path": "en/api/java/messages/batches/delete.md", + "sha256": "e0b8f507d75c528ba15e08056989139d14e0f70172ce518ec9105b5a2cfbb48d", + "size": 1498 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/messages/batches/results", + "status": "success", + "path": "en/api/java/messages/batches/results.md", + "sha256": "c19a37d789c91d5188a586635b6b32793a553f7dae8a3495d5f8e3d979f38ac2", + "size": 30615 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/models", + "status": "success", + "path": "en/api/java/models.md", + "sha256": "2836a564d4084b7758854d159e95db66946c1dc097992845229a793a614e37d6", + "size": 24358 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/models/list", + "status": "success", + "path": "en/api/java/models/list.md", + "sha256": "0502660a1dfae1c5017dd80764120a50834e69dc828a574c6eadfa64c51fc7ab", + "size": 7025 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/models/retrieve", + "status": "success", + "path": "en/api/java/models/retrieve.md", + "sha256": "7637a1ef9032e6eec20597c33c38f3c737ab8c121e42f03862b82a51e162b038", + "size": 6663 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta", + "status": "success", + "path": "en/api/java/beta.md", + "sha256": "ef9a9522b43d7a8ef9699fea0581b31f59d3b91bf086728ceb3c02c5f56b2823", + "size": 89170 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/models", + "status": "success", + "path": "en/api/java/beta/models.md", + "sha256": "b7a5fe31adea3be109a31decfcfcf5ba6bacb78a1da5c0d0df0227e708b96f9d", + "size": 24857 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/models/list", + "status": "success", + "path": "en/api/java/beta/models/list.md", + "sha256": "f8008adf0b6556ad1ecb6a01a04cceadc272d4a8d91b9543782440a569cd2e85", + "size": 7133 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/models/retrieve", + "status": "success", + "path": "en/api/java/beta/models/retrieve.md", + "sha256": "cc402170d87188ff50a9f88129c586556d9b384055915c7792451d0bf1ddf170", + "size": 6787 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/messages", + "status": "success", + "path": "en/api/java/beta/messages.md", + "sha256": "c22761d33110f920fc5a86dce46220d703315e4c098ce4d06de8394ab101c41f", + "size": 1120410 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/messages/create", + "status": "success", + "path": "en/api/java/beta/messages/create.md", + "sha256": "1d8fbe5dcf07b45c9be5c71cfe5a2e144532cb290b05b391fc3ec6f1c8fd45e8", + "size": 151042 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/messages/count_tokens", + "status": "success", + "path": "en/api/java/beta/messages/count_tokens.md", + "sha256": "18ab59769c3aa065f8fba7d5563e3f1a47a40fc5e16f4b26661f84287cbfd70d", + "size": 116753 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches", + "status": "success", + "path": "en/api/java/beta/messages/batches.md", + "sha256": "b42d5978f08ecdedbbab3d1d1b956a9d5d12750a43598c9aa4e93a7cd40b4702", + "size": 316565 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches/create", + "status": "success", + "path": "en/api/java/beta/messages/batches/create.md", + "sha256": "92309f57a0fa6fdc4bc7ce1def076047e77ea8bc18d601b0170b2b50387047c8", + "size": 142071 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches/retrieve", + "status": "success", + "path": "en/api/java/beta/messages/batches/retrieve.md", + "sha256": "cf574904c2c1e42e1867a969fb2322e89b3a11633dc0c5c5cdaf7def932eeecb", + "size": 5530 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches/list", + "status": "success", + "path": "en/api/java/beta/messages/batches/list.md", + "sha256": "6ae8f6a6c0454b151b030ec6eb2338c77e31df767029394c05f853b62b493fde", + "size": 5734 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches/cancel", + "status": "success", + "path": "en/api/java/beta/messages/batches/cancel.md", + "sha256": "7ad326d61657c42b76452acaca4c3a5ca5fc43fbe40e1f9e2835ccee9e970f49", + "size": 5834 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches/delete", + "status": "success", + "path": "en/api/java/beta/messages/batches/delete.md", + "sha256": "d1058a5e4b093dba440abad7fcff8b5da210e58cd5b73f850ab180e93e5c2f43", + "size": 2978 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches/results", + "status": "success", + "path": "en/api/java/beta/messages/batches/results.md", + "sha256": "8595d2a672d287eafcfbb941b9bbe446ac2e3a16229217da5097a5d8aca4bdb5", + "size": 41002 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/agents", + "status": "success", + "path": "en/api/java/beta/agents.md", + "sha256": "68f21482e9a686ded2e04ef6f914a9caa48ec783017a2c939ebdb4880fa28f5b", + "size": 89195 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/agents/create", + "status": "success", + "path": "en/api/java/beta/agents/create.md", + "sha256": "5968f42ca67cd1ec0f468d0f0341bd64e5aa26ad6cf655468715a3e0dea3941f", + "size": 89220 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/agents/list", + "status": "success", + "path": "en/api/java/beta/agents/list.md", + "sha256": "78e36e93990914c9f004cbcf798d0bf0d4e37fa37853f5cc64e3b099f4844d4f", + "size": 9034 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/agents/retrieve", + "status": "success", + "path": "en/api/java/beta/agents/retrieve.md", + "sha256": "e5314b3baab24be78adf61cb40bc3fad4efbe9450da27ad385c75006c886c536", + "size": 8814 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/agents/update", + "status": "success", + "path": "en/api/java/beta/agents/update.md", + "sha256": "0789cbb949c5f8ff5292ef583be4bbda040454ca246d49e414f4f4e8bafca157", + "size": 89220 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/agents/archive", + "status": "success", + "path": "en/api/java/beta/agents/archive.md", + "sha256": "82bea28a510f2d2022290edd87235e3cef53893e5fdc014bb89d2e7a80edd099", + "size": 8703 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/agents/versions", + "status": "success", + "path": "en/api/java/beta/agents/versions.md", + "sha256": "bddf02aa5841123289962f0ff9cc62cff2f418cc0604b33fac1d206f56a41bc0", + "size": 8853 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/agents/versions/list", + "status": "success", + "path": "en/api/java/beta/agents/versions/list.md", + "sha256": "2c49c5ba0cd64eef181c0507d7b14a3d33f88da6a4934b65be0e11d1ea8e5424", + "size": 8841 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/environments", + "status": "success", + "path": "en/api/java/beta/environments.md", + "sha256": "31776d7c27665655abec6f5fc69c5b6a6bd4ad43dfdc97fc950751fa11bd2ec3", + "size": 37232 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/environments/create", + "status": "success", + "path": "en/api/java/beta/environments/create.md", + "sha256": "c61e5db9e56333dd6095cbc04072c4bd1f01d652786f3d987b979825ba2a29bd", + "size": 5224 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/environments/list", + "status": "success", + "path": "en/api/java/beta/environments/list.md", + "sha256": "e70c8f622236c4035dec55775fe856d4342c50e14b146778587a7709c1d3bfab", + "size": 4973 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/environments/retrieve", + "status": "success", + "path": "en/api/java/beta/environments/retrieve.md", + "sha256": "c0e0b4d980ed486c843948a7b85a12a6afd29228701f6f07fd49a9a007b3c7d5", + "size": 4773 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/environments/update", + "status": "success", + "path": "en/api/java/beta/environments/update.md", + "sha256": "f149ab4369a006ecab07824a78cdb35d70cf7258d685ae231e77f4fee2fe0b19", + "size": 5244 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/environments/delete", + "status": "success", + "path": "en/api/java/beta/environments/delete.md", + "sha256": "fa85b537e4e5ddcd3c54a8845fadd1d92fd80e2de654cc39b506a466a4e8f2c6", + "size": 2726 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/environments/archive", + "status": "success", + "path": "en/api/java/beta/environments/archive.md", + "sha256": "9081ef1b889111c717d9d3243a22edd61e6f4944d60e0f64a8ae84566fc290c5", + "size": 4827 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions", + "status": "success", + "path": "en/api/java/beta/sessions.md", + "sha256": "220b056df26125e6d50156d777d3ef5a33637c75603b279368fbbdd690c86b40", + "size": 329756 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/create", + "status": "success", + "path": "en/api/java/beta/sessions/create.md", + "sha256": "9036cba14a601f426dc9998bba72269f75c936d588755787f44969946dc1beca", + "size": 14205 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/list", + "status": "success", + "path": "en/api/java/beta/sessions/list.md", + "sha256": "1de7038da368311fa47885bc856342324184845ca98bd02ee94f95010731448c", + "size": 12585 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/retrieve", + "status": "success", + "path": "en/api/java/beta/sessions/retrieve.md", + "sha256": "da1b5ebc7e63747fef4271b4ea47c74fba94aa69758b2719c7e71c2e7d5ad230", + "size": 11683 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/update", + "status": "success", + "path": "en/api/java/beta/sessions/update.md", + "sha256": "e14d51cf899a7d624306d94a28bf95b056b950b5db833c2f01aa39d0e9696cd8", + "size": 12059 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/delete", + "status": "success", + "path": "en/api/java/beta/sessions/delete.md", + "sha256": "b881c6f7be65af9c6c407abdec11d78f03826bc30989c83d83cd581f6fb31828", + "size": 2561 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/archive", + "status": "success", + "path": "en/api/java/beta/sessions/archive.md", + "sha256": "118442309bd586c057f2168033ed24460d3cd729237ae9ddb8f63df24049c076", + "size": 11689 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/events", + "status": "success", + "path": "en/api/java/beta/sessions/events.md", + "sha256": "4c044e1d4cb2977007d77fb4e4cc2b2e4d49f49fbcce3e4e7292b647f7bf1ed4", + "size": 225769 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/events/list", + "status": "success", + "path": "en/api/java/beta/sessions/events/list.md", + "sha256": "e91256530ec90bbfcf4b4045ed9e82a4ec297a6bf0eeda4849daf6d442c1866b", + "size": 34860 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/events/send", + "status": "success", + "path": "en/api/java/beta/sessions/events/send.md", + "sha256": "b85257a41afb66350f9d1f1c09c788c5eae19b18163ad848c5daea17e3ec5ce6", + "size": 20118 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/events/stream", + "status": "success", + "path": "en/api/java/beta/sessions/events/stream.md", + "sha256": "1fdab2a465d0af37363bdee8593790d406b4742a00b63787ad59165bd9097a8b", + "size": 34752 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/resources", + "status": "success", + "path": "en/api/java/beta/sessions/resources.md", + "sha256": "cdab8f6e8b91ed0cc5b6383f2cfa2f0dcc973735ece1a74ef41d263f524782b0", + "size": 19826 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/resources/add", + "status": "success", + "path": "en/api/java/beta/sessions/resources/add.md", + "sha256": "21b5c2cb8f8ed986391f251aea7a76f57af9bd4b6c8133d00af57e997db55167", + "size": 3243 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/resources/list", + "status": "success", + "path": "en/api/java/beta/sessions/resources/list.md", + "sha256": "8b260c616a9fcf3a6106e4f38a51a50fadcf6acf1600f90c22c555dd859536bc", + "size": 3670 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/resources/retrieve", + "status": "success", + "path": "en/api/java/beta/sessions/resources/retrieve.md", + "sha256": "4e92cdabf956f6fe1aa5f1c4d624a75b0e1168d7a302f501996a89b69503a14c", + "size": 3724 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/resources/update", + "status": "success", + "path": "en/api/java/beta/sessions/resources/update.md", + "sha256": "ebd533b3ce265dc8bf791921ba0674eb19061f21bf1a569520b988a26fe20ac2", + "size": 3903 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/sessions/resources/delete", + "status": "success", + "path": "en/api/java/beta/sessions/resources/delete.md", + "sha256": "c447bd2f3cf5273b6f3ee322e2e33b88b2400aada8672be4614556ef6c2b55d7", + "size": 2846 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults", + "status": "success", + "path": "en/api/java/beta/vaults.md", + "sha256": "0343c4c567a3e454e707cb2d8aa8e8f55cb1e1764a9298bda23437b769ca43ba", + "size": 67084 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/create", + "status": "success", + "path": "en/api/java/beta/vaults/create.md", + "sha256": "158f700151c4c48f9ed936923292da30dd0949e7dbea9010dfb92c8dce024380", + "size": 3084 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/list", + "status": "success", + "path": "en/api/java/beta/vaults/list.md", + "sha256": "9f5c70eb5957a14ce23f03ce650e23a8d0ba4ca4b252ceccf3735e5fa29a8a07", + "size": 3042 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/retrieve", + "status": "success", + "path": "en/api/java/beta/vaults/retrieve.md", + "sha256": "ef3a328027691caca00c93f2edfba9d67ef1e818073d79ba81dba8db8ed9b1f8", + "size": 2884 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/update", + "status": "success", + "path": "en/api/java/beta/vaults/update.md", + "sha256": "343e185b2a930bb5ead417e1919cac643440930ac04b73ab5f62c7ecc4d1b99d", + "size": 3121 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/delete", + "status": "success", + "path": "en/api/java/beta/vaults/delete.md", + "sha256": "8d04c71753c7b0eca8451930257da4bc754c0c3a0d127d1181837ec2eb8e4ad1", + "size": 2540 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/archive", + "status": "success", + "path": "en/api/java/beta/vaults/archive.md", + "sha256": "a3c37b89d231f1c2830e66ca54e59327dbb64e2c23da26a541a48e13802995c2", + "size": 2890 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/credentials", + "status": "success", + "path": "en/api/java/beta/vaults/credentials.md", + "sha256": "f47d594f386cd674bffd97eef2d9e826f3f288d58602c77fecc3d01042e6fba8", + "size": 48662 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/credentials/create", + "status": "success", + "path": "en/api/java/beta/vaults/credentials/create.md", + "sha256": "aae064c7da87a16f27a6d2ca297314472988f0f2488132c1c787e12d91d46dde", + "size": 8061 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/credentials/list", + "status": "success", + "path": "en/api/java/beta/vaults/credentials/list.md", + "sha256": "8198addc59b505c40c9ae1c0a6496bd7a6fe7f2dfcde761c6bc890fd23232b17", + "size": 5325 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/credentials/retrieve", + "status": "success", + "path": "en/api/java/beta/vaults/credentials/retrieve.md", + "sha256": "6ee8f4412190c6b8761eb69419c7465d920ba5da0513f2582394f160e14c59ad", + "size": 5280 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/credentials/update", + "status": "success", + "path": "en/api/java/beta/vaults/credentials/update.md", + "sha256": "7a75f68769dccf2c39fe323384b5520a4cc50faa0ca90cf2395b716f270f0bac", + "size": 7388 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/credentials/delete", + "status": "success", + "path": "en/api/java/beta/vaults/credentials/delete.md", + "sha256": "96b9b0afcaef832763545914318b40081895e190ecb29cf568ef64d027ad9ba2", + "size": 2880 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/vaults/credentials/archive", + "status": "success", + "path": "en/api/java/beta/vaults/credentials/archive.md", + "sha256": "f5d96ef55b118fb53aac4182c9953fae938b114e5eccfd9168e8c2a1333532e1", + "size": 5285 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/files", + "status": "success", + "path": "en/api/java/beta/files.md", + "sha256": "23002b6ed568b674c669ec60db8b5a26838932a99f213a6b3236b6007e1d9c70", + "size": 16478 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/files/upload", + "status": "success", + "path": "en/api/java/beta/files/upload.md", + "sha256": "61a590511c16064f5d60957a0eb13874efffb0b2e27cb7117687e2dc1d588bb9", + "size": 3337 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/files/list", + "status": "success", + "path": "en/api/java/beta/files/list.md", + "sha256": "278ffa42eadeb9b940bb2a0f819601a2de1cd0271e92237fbccfc16698a5f5a0", + "size": 3680 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/files/download", + "status": "success", + "path": "en/api/java/beta/files/download.md", + "sha256": "873efda662622539f6628aabdc997213d05ca3e2c9a18f7c62282b7a9c989038", + "size": 2259 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/files/retrieve_metadata", + "status": "success", + "path": "en/api/java/beta/files/retrieve_metadata.md", + "sha256": "22f07e237067f5d2a8aa9c5dac2bd81d57c1fdb35c55e15bb53c933809df38a2", + "size": 3270 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/files/delete", + "status": "success", + "path": "en/api/java/beta/files/delete.md", + "sha256": "62814002bd38bb7e1303b97aaa8df0b350676fc7f514d768bc9265b84501e3c6", + "size": 2477 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/skills", + "status": "success", + "path": "en/api/java/beta/skills.md", + "sha256": "dddd8e74a9c947461f2665d4b981c22cb3bc9054e357b00ba9734ae6a1a8171d", + "size": 26970 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/skills/create", + "status": "success", + "path": "en/api/java/beta/skills/create.md", + "sha256": "d51bf0e72c9fa81e174363c81c6992c98d540e7d43304feec731c22d4b9a1d8d", + "size": 3482 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/skills/list", + "status": "success", + "path": "en/api/java/beta/skills/list.md", + "sha256": "f049b386e2bc5b4e8ea7e3886fce8f599869eff7864fafe91ef56c86bfe56a82", + "size": 3641 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/skills/retrieve", + "status": "success", + "path": "en/api/java/beta/skills/retrieve.md", + "sha256": "80bf2ed26b08ea407f228269217989007e78927cf33d45527905d32c83e7e3bd", + "size": 3295 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/skills/delete", + "status": "success", + "path": "en/api/java/beta/skills/delete.md", + "sha256": "2c3845d492a212064f735594cbb4879d57e404749fe6ba3a71e5b58f7f1fc234", + "size": 2602 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/skills/versions", + "status": "success", + "path": "en/api/java/beta/skills/versions.md", + "sha256": "3c2a1a0eb11ffd3da61ad111518b7c45c80724a10c60387994cd1b09e91ab53a", + "size": 13936 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/skills/versions/create", + "status": "success", + "path": "en/api/java/beta/skills/versions/create.md", + "sha256": "a76ec77245bd8b4f2157358cc4bfbf3feacfd1f72bfd4e8716776126ae64087a", + "size": 3607 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/skills/versions/list", + "status": "success", + "path": "en/api/java/beta/skills/versions/list.md", + "sha256": "77ef95f1dd8c7cd3d15bf62d8d498f7848f01de6e6e21d1c43b0480edcc6bdc4", + "size": 3598 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/skills/versions/retrieve", + "status": "success", + "path": "en/api/java/beta/skills/versions/retrieve.md", + "sha256": "5e01bd747e6a1dd67837e20b04406e54df40991d010437b57f4658ffad3b1374", + "size": 3714 + }, + { + "url": "https://platform.claude.com/docs/en/api/java/beta/skills/versions/delete", + "status": "success", + "path": "en/api/java/beta/skills/versions/delete.md", + "sha256": "5c33eeda7969b5fb84cb0ceadfd49c2a29fe58df3e8542960f65a333b8c489b6", + "size": 3002 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/completions", + "status": "success", + "path": "en/api/go/completions.md", + "sha256": "258eb4473ea8934052c5c5f8f2fbc843dcfa7f87c4bb2a490d25ff774d528d6b", + "size": 12367 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/completions/create", + "status": "success", + "path": "en/api/go/completions/create.md", + "sha256": "4872a24cd14cc5a670b11b8b5f412a34bf0676fa75e57145f327321ac9221ac5", + "size": 9152 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/messages", + "status": "success", + "path": "en/api/go/messages.md", + "sha256": "9ba4681b22eae2cd038bce4d2088b0ba7b70cc5e8896846f3a191c6885246651", + "size": 1098389 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/messages/create", + "status": "success", + "path": "en/api/go/messages/create.md", + "sha256": "432bdd02e18bbfdde2140fa3c7b5bbe7ab468186dd47d0572050677578e80edd", + "size": 144362 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/messages/count_tokens", + "status": "success", + "path": "en/api/go/messages/count_tokens.md", + "sha256": "2170126f9cfa73c768b1df3c7089d08fc452b313404a3178bcec4f813b5e5b05", + "size": 112872 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/messages/batches", + "status": "success", + "path": "en/api/go/messages/batches.md", + "sha256": "8b60f4e4d98052aab92341a551ea9945f6fe4a4e5646676e71226f3421a43293", + "size": 288548 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/messages/batches/create", + "status": "success", + "path": "en/api/go/messages/batches/create.md", + "sha256": "5267aeeff2162eb8285464aeff2aff400a39823327b2fc480e7af518afecc5a0", + "size": 134102 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/messages/batches/retrieve", + "status": "success", + "path": "en/api/go/messages/batches/retrieve.md", + "sha256": "bdc366efbc71476c7dc058e4d19442d5db0216f412475fee3101f3ed5884a943", + "size": 3946 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/messages/batches/list", + "status": "success", + "path": "en/api/go/messages/batches/list.md", + "sha256": "13803b84761d4e03026bfa836b268d1f58ebf2708efa4815f72c762dd11cb110", + "size": 4271 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/messages/batches/cancel", + "status": "success", + "path": "en/api/go/messages/batches/cancel.md", + "sha256": "6a096b0fc9b9b960628e7930aa2196cb7b7145e55a77b008a554f0c28afc1358", + "size": 4268 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/messages/batches/delete", + "status": "success", + "path": "en/api/go/messages/batches/delete.md", + "sha256": "646f74b47911415e5bf68f98faf63b3195123369f63ff9ea9d47029de680a535", + "size": 1298 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/messages/batches/results", + "status": "success", + "path": "en/api/go/messages/batches/results.md", + "sha256": "9390494cfc7cf813a722ed8237a6ed44348964bc8d1a1a2bbadaf07e9dba5cc6", + "size": 35972 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/models", + "status": "success", + "path": "en/api/go/models.md", + "sha256": "865e16ed0847614e83a4b368797500b2a28c5f002408a17a0edd54a88f4e6213", + "size": 25226 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/models/list", + "status": "success", + "path": "en/api/go/models/list.md", + "sha256": "5be3c40932480aec3a544793fc6a7afd902e3bc9f1f9193fe4b0225319093890", + "size": 7597 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/models/retrieve", + "status": "success", + "path": "en/api/go/models/retrieve.md", + "sha256": "e73d1a9941819fc6d592c79ffb7babce0c2a7136dc1e8ae6935690f2a5f41ff0", + "size": 7172 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta", + "status": "success", + "path": "en/api/go/beta.md", + "sha256": "6356e59bef0f4abe30a4e9c473f4925150f01bb271e0f5d5de37078f94d1343e", + "size": 2175479 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/models", + "status": "success", + "path": "en/api/go/beta/models.md", + "sha256": "1091a3ecbab244ccf24335545b035b5639fe1fdf5198b5c1688358042ac678df", + "size": 25713 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/models/list", + "status": "success", + "path": "en/api/go/beta/models/list.md", + "sha256": "ac5061f3e287a0027c7aa1000f0d91d62cd03d60c500424b8cd1d9f9adbd590f", + "size": 7703 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/models/retrieve", + "status": "success", + "path": "en/api/go/beta/models/retrieve.md", + "sha256": "41c9f34d88f32d266b10fe3a3a33be9bf0bfea5b2c91efeb3c0fe227f2ccca43", + "size": 7286 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/messages", + "status": "success", + "path": "en/api/go/beta/messages.md", + "sha256": "a1a6692a2074fe979403937d6fda78b8066d1f33ab996922e3f7443a76af7e53", + "size": 1344070 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/messages/create", + "status": "success", + "path": "en/api/go/beta/messages/create.md", + "sha256": "6ae45df6144f951246b837324ba1559d684315ee1fce0db61dacdbbf93f5041e", + "size": 180206 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/messages/count_tokens", + "status": "success", + "path": "en/api/go/beta/messages/count_tokens.md", + "sha256": "748c7d0e31e86febf5d708f4fddddf317c1e0b5aa0d8068d799731dd0033f9a1", + "size": 139087 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches", + "status": "success", + "path": "en/api/go/beta/messages/batches.md", + "sha256": "7e546d13fb30fdba790b266cdd323fe75a31e57320681f6f9c95fff7b1bd369c", + "size": 371530 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches/create", + "status": "success", + "path": "en/api/go/beta/messages/batches/create.md", + "sha256": "511fc56a29944a59af71aea8dd4ae838f1c573107dfdca09e1a7af23c2984b30", + "size": 165909 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches/retrieve", + "status": "success", + "path": "en/api/go/beta/messages/batches/retrieve.md", + "sha256": "ce6581e54d021d0c07e6fd38cd54f5282b11f8de9522569e56c514ac4d159871", + "size": 6307 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches/list", + "status": "success", + "path": "en/api/go/beta/messages/batches/list.md", + "sha256": "38077f4677214a6adf94ae166ff5557013e81dc1df7b6a257f1ecb6761c7546a", + "size": 6581 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches/cancel", + "status": "success", + "path": "en/api/go/beta/messages/batches/cancel.md", + "sha256": "c63295ebed755b6013db49bc6564e28de96a13b2f73a66edfe791654a1d12586", + "size": 6633 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches/delete", + "status": "success", + "path": "en/api/go/beta/messages/batches/delete.md", + "sha256": "a4f6b39690fe48603a984ec9ced9e3b32d0fa780c81c676e8592e197788f7518", + "size": 3631 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches/results", + "status": "success", + "path": "en/api/go/beta/messages/batches/results.md", + "sha256": "02a99b135ac92f5827a0a00fc01164da60a9a8ad57e85288f1c136c2a5cb967f", + "size": 48382 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/agents", + "status": "success", + "path": "en/api/go/beta/agents.md", + "sha256": "fdf8236079daaae6221901c1499d0a2b5f2586695dc31f2f39b89c8c47a559da", + "size": 147355 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/agents/create", + "status": "success", + "path": "en/api/go/beta/agents/create.md", + "sha256": "e6cf08f44d77687d7991fd1a727beb7a95cde9d2426513c4fb6bb688ae47b11e", + "size": 25361 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/agents/list", + "status": "success", + "path": "en/api/go/beta/agents/list.md", + "sha256": "59f614cf4446edd08d15487a83b787effbf0f92d577a65a5e16f01dd975a2fe0", + "size": 13270 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/agents/retrieve", + "status": "success", + "path": "en/api/go/beta/agents/retrieve.md", + "sha256": "a315cd868f72c5685bb3337069bf99c962b320c66a1311d9203bf841a14e2ce8", + "size": 12979 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/agents/update", + "status": "success", + "path": "en/api/go/beta/agents/update.md", + "sha256": "c1291b161334e9bb6ab42c56f97c20d4d77d0557fdd1535f6e98beb88be5318d", + "size": 25964 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/agents/archive", + "status": "success", + "path": "en/api/go/beta/agents/archive.md", + "sha256": "d2c043ca37e580ce6aa124f59a52a1bb88df2f60e2f94ed89b129aec6d4c4d42", + "size": 12855 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/agents/versions", + "status": "success", + "path": "en/api/go/beta/agents/versions.md", + "sha256": "32ce5f6a1df30c724160fc920c543f5b32d8e17f0b66d51681d988974098a3b1", + "size": 13058 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/agents/versions/list", + "status": "success", + "path": "en/api/go/beta/agents/versions/list.md", + "sha256": "c04809a74281bda047aa5b7bc9fdcb1fb80791034deb6cc8436543704152a2da", + "size": 13046 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/environments", + "status": "success", + "path": "en/api/go/beta/environments.md", + "sha256": "fb0950982ed2e4cff1d5654d66041a1703fcf2ecc485db3a269ba18b02bcad8d", + "size": 41610 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/environments/create", + "status": "success", + "path": "en/api/go/beta/environments/create.md", + "sha256": "9840e14195ca4679045ce2683ca54e8d35e4f752a80065704e86e97ba5bf199d", + "size": 5906 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/environments/list", + "status": "success", + "path": "en/api/go/beta/environments/list.md", + "sha256": "875590489b8556067aacaf10fcba2cd29341419d2ada11699b62cdcfa1c8983f", + "size": 5697 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/environments/retrieve", + "status": "success", + "path": "en/api/go/beta/environments/retrieve.md", + "sha256": "385ea2be975ff746584e0d73d7ab90c5ed6591a3115a03fe8f591f70a91273f4", + "size": 5445 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/environments/update", + "status": "success", + "path": "en/api/go/beta/environments/update.md", + "sha256": "7393f252a26facd7e7ecc2e68fd2440984d63b23df884fff4980fd7b11afa912", + "size": 6031 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/environments/delete", + "status": "success", + "path": "en/api/go/beta/environments/delete.md", + "sha256": "dda626798415d003465d9071573b57b9adacf7197480d3bb3a49dd629e0b2462", + "size": 3360 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/environments/archive", + "status": "success", + "path": "en/api/go/beta/environments/archive.md", + "sha256": "e67de5d5a2b15e2fa0ca86c51a5c5e4115f851bd390f203c48cd7f4380e537aa", + "size": 5519 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions", + "status": "success", + "path": "en/api/go/beta/sessions.md", + "sha256": "28be817b31b70cef4e96331a4d685923537a92b23cc23df7c0e5854018d6bc1b", + "size": 470844 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/create", + "status": "success", + "path": "en/api/go/beta/sessions/create.md", + "sha256": "25b11b7c49f9204da4b3131961353ae6b18a745fb2c4568c4cc4cbd5f03a7253", + "size": 20014 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/list", + "status": "success", + "path": "en/api/go/beta/sessions/list.md", + "sha256": "f4b4b907aa8d3700cb5020d128c8ea1f86f9ceec02777591cc67ac29ba8a99a3", + "size": 17853 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/retrieve", + "status": "success", + "path": "en/api/go/beta/sessions/retrieve.md", + "sha256": "54a81b5220744f7755c93a13096c9ff9e6bdace374959d6bfe328ee62e4b664c", + "size": 16647 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/update", + "status": "success", + "path": "en/api/go/beta/sessions/update.md", + "sha256": "f2b1996c1a7df943d5c0ffe2b8db30e3917c83325691d08fe0d3a19d76bf0af3", + "size": 17115 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/delete", + "status": "success", + "path": "en/api/go/beta/sessions/delete.md", + "sha256": "b9a7eef093edd90a07658d206bd4b1195f34791ecf2433191db1a0121bf8c4f7", + "size": 3292 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/archive", + "status": "success", + "path": "en/api/go/beta/sessions/archive.md", + "sha256": "403fa5b8b300e729708b92b3da283db09d6fdc9a1f7902e3c7b8942a0e6cee85", + "size": 16673 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/events", + "status": "success", + "path": "en/api/go/beta/sessions/events.md", + "sha256": "c18bab9d5a9e6711ee6d7cf40189913e96cbf1d1adeb0c6fbabac990bfb159df", + "size": 325501 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/events/list", + "status": "success", + "path": "en/api/go/beta/sessions/events/list.md", + "sha256": "ef186a6cae36ac551f7f13773b762646f6b8a495bd6a17495753ee226da65645", + "size": 49976 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/events/send", + "status": "success", + "path": "en/api/go/beta/sessions/events/send.md", + "sha256": "8771df85c3e73734477b097385f79f9bef797393a8dcf7f2c55de1fb05f43f95", + "size": 28380 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/events/stream", + "status": "success", + "path": "en/api/go/beta/sessions/events/stream.md", + "sha256": "3376de6f490e389053220281e0a96ca447489a1a46f8c01e6c7ba7f4727b62a1", + "size": 49509 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/resources", + "status": "success", + "path": "en/api/go/beta/sessions/resources.md", + "sha256": "7d4c3ebc2dfcef1b57bde7eb059efe1ee4a80d8c2d6a29156157a890b81d51ca", + "size": 25448 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/resources/add", + "status": "success", + "path": "en/api/go/beta/sessions/resources/add.md", + "sha256": "1dc056cf901548327270ebbf43c4ed2a5b88e1583294397e152a129925cedd12", + "size": 3795 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/resources/list", + "status": "success", + "path": "en/api/go/beta/sessions/resources/list.md", + "sha256": "108288d855ed4f4cff90d6126b5863e70395fb5d0db98cd5ff5ac3820583b297", + "size": 4826 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/resources/retrieve", + "status": "success", + "path": "en/api/go/beta/sessions/resources/retrieve.md", + "sha256": "c2f7112269f70d4319c5c61b0190f8bea0761890cc717f3e4ef5b357b7d8e811", + "size": 4746 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/resources/update", + "status": "success", + "path": "en/api/go/beta/sessions/resources/update.md", + "sha256": "3e09d2bf49b7e98fec04d3a5b3019b349e98e115326ace7295c9daf1edc52b56", + "size": 4984 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/sessions/resources/delete", + "status": "success", + "path": "en/api/go/beta/sessions/resources/delete.md", + "sha256": "3b1a2e7be322d3020d8523561e5f60bd50f010de859cc07faaf4ecc25aacd164", + "size": 3553 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults", + "status": "success", + "path": "en/api/go/beta/vaults.md", + "sha256": "11459be8cd873173214aa66bf5581f976b3b80607702baaf56515b5e60114182", + "size": 86822 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/create", + "status": "success", + "path": "en/api/go/beta/vaults/create.md", + "sha256": "1ac5527ff326198ac5c9527abbaa6c8d20502bf8ca23a3708e8c5bcc90036308", + "size": 3744 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/list", + "status": "success", + "path": "en/api/go/beta/vaults/list.md", + "sha256": "7d0d832bbabf75b745f564cd1f327ff8d26b2c57f2e41f29e89f22e40fcd197f", + "size": 3804 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/retrieve", + "status": "success", + "path": "en/api/go/beta/vaults/retrieve.md", + "sha256": "14f0cfc3e14bd60be5868ce82699ed2d58a4b39c8f6708ae1f691362bc605f5b", + "size": 3556 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/update", + "status": "success", + "path": "en/api/go/beta/vaults/update.md", + "sha256": "81c204e04ea0f428f10036a3637f67256e1bf1d64fa08dd3e951769dd2828e92", + "size": 3874 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/delete", + "status": "success", + "path": "en/api/go/beta/vaults/delete.md", + "sha256": "edc9f9a28b9c76d00e2314e2fba21ccc8ba546b5b164be1963dc840cadff04dc", + "size": 3273 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/archive", + "status": "success", + "path": "en/api/go/beta/vaults/archive.md", + "sha256": "756424b98eebd5fff9837ad7cca80f3854b1796af2a73f99fbcddf6920ea2aa8", + "size": 3582 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/credentials", + "status": "success", + "path": "en/api/go/beta/vaults/credentials.md", + "sha256": "2d6a967ee310697b6b890396540b1fff112822769e38bf338bd2e74a14e3c50c", + "size": 63950 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/credentials/create", + "status": "success", + "path": "en/api/go/beta/vaults/credentials/create.md", + "sha256": "55eedf073399d5264d22b3ded1d02bea93108232c95be977034ec738df9fbd90", + "size": 10268 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/credentials/list", + "status": "success", + "path": "en/api/go/beta/vaults/credentials/list.md", + "sha256": "9ddad81fa89f7b9811ab13a5e3a1fd2136baf166ddec274b772ad28372c866cc", + "size": 6874 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/credentials/retrieve", + "status": "success", + "path": "en/api/go/beta/vaults/credentials/retrieve.md", + "sha256": "83f8100aeee746fb2edf8ad40f0c3ddd6fda2f3895d6d49b6ec0548f7e958a96", + "size": 6695 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/credentials/update", + "status": "success", + "path": "en/api/go/beta/vaults/credentials/update.md", + "sha256": "7a1d43235933d3c269384b42e15df3ce65bc78f09a8d8565c340ce148695ddf7", + "size": 9524 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/credentials/delete", + "status": "success", + "path": "en/api/go/beta/vaults/credentials/delete.md", + "sha256": "b01e5b5471c49e9599268136c7d74fc7832b91b961c26bfc948a94a109ac3c61", + "size": 3567 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/vaults/credentials/archive", + "status": "success", + "path": "en/api/go/beta/vaults/credentials/archive.md", + "sha256": "60249c3faf4a5b3a69a6d4fbd1cb1abd65e4de07ad2ce3c29d1ea21a10a9c453", + "size": 6723 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/files", + "status": "success", + "path": "en/api/go/beta/files.md", + "sha256": "5b7bbc4f2bb2c2feba802641d668a3106de10ea0c471f6636d6211d5ce31a52f", + "size": 19703 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/files/upload", + "status": "success", + "path": "en/api/go/beta/files/upload.md", + "sha256": "b5094d86aed2c8bc0e52f2355f7106268c362f0b600e99923a6fb16bc6e6c5c1", + "size": 3886 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/files/list", + "status": "success", + "path": "en/api/go/beta/files/list.md", + "sha256": "a227e06b8d9f0cd7b028df9e4d7b173425c56df14ac1602f09478244a5fe5e1e", + "size": 4361 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/files/download", + "status": "success", + "path": "en/api/go/beta/files/download.md", + "sha256": "df267357f6aba887df220e3fe76e0859d46896d6343b37f9ecd77e78abd9b37b", + "size": 2956 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/files/retrieve_metadata", + "status": "success", + "path": "en/api/go/beta/files/retrieve_metadata.md", + "sha256": "b3f0e02fc2aa300230cc384d2c8c57826503c007e8f168e27296e39b90830f1c", + "size": 3846 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/files/delete", + "status": "success", + "path": "en/api/go/beta/files/delete.md", + "sha256": "3a171bd89154b720a2b8917da6a2ba0064fa000771507b56a46477421c1bef3f", + "size": 3165 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/skills", + "status": "success", + "path": "en/api/go/beta/skills.md", + "sha256": "51485499a1d553072fc5d5dee57d53c6581ae3d88370903ce878a618570169dd", + "size": 31925 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/skills/create", + "status": "success", + "path": "en/api/go/beta/skills/create.md", + "sha256": "2f57b96ec258957dd1f7204386dab12e1b07677bd62ef5ada8b5f55436a59877", + "size": 4105 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/skills/list", + "status": "success", + "path": "en/api/go/beta/skills/list.md", + "sha256": "6863500288e9acb50132d7e9ed6d61cf4e4ba8ad3c817b299d13abd33693a123", + "size": 4333 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/skills/retrieve", + "status": "success", + "path": "en/api/go/beta/skills/retrieve.md", + "sha256": "94c0d35e9ede93c6a259651a32909715be3ef28a318f858ef1cc20580ae25ea4", + "size": 3870 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/skills/delete", + "status": "success", + "path": "en/api/go/beta/skills/delete.md", + "sha256": "e87ea128ed1552d42d576860063343a88bda0501618eb85aacc94f440428e210", + "size": 3233 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/skills/versions", + "status": "success", + "path": "en/api/go/beta/skills/versions.md", + "sha256": "679144dc532fc43757d520be14ac8bf5bf424646786d4382517aee2c9162327f", + "size": 16370 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/skills/versions/create", + "status": "success", + "path": "en/api/go/beta/skills/versions/create.md", + "sha256": "13f82099c996eacee47b4dd79c12ee1a2d9ffef8c890986628079059e965aa21", + "size": 4241 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/skills/versions/list", + "status": "success", + "path": "en/api/go/beta/skills/versions/list.md", + "sha256": "2947c6090bbc5dec285f5ed52a2a9a86f035ee991559170c028cc00a4b2501fd", + "size": 4298 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/skills/versions/retrieve", + "status": "success", + "path": "en/api/go/beta/skills/versions/retrieve.md", + "sha256": "0e07e198f9f55fb1472d6e16a90a142e056012b99cbd605ab60e3b2f45405c16", + "size": 4244 + }, + { + "url": "https://platform.claude.com/docs/en/api/go/beta/skills/versions/delete", + "status": "success", + "path": "en/api/go/beta/skills/versions/delete.md", + "sha256": "ecd67ec472621fe2d366a1d54dc74af6219c090a4a0dfc6595e5f769ff9e2942", + "size": 3572 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/completions", + "status": "success", + "path": "en/api/ruby/completions.md", + "sha256": "e3c172a6ec3cee6de705912dd7cb25a68c760dad918542fcca45224e2c59aa56", + "size": 11565 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/completions/create", + "status": "success", + "path": "en/api/ruby/completions/create.md", + "sha256": "40f7f289cb3fa31dcfd00cb9fa92eff2d0b19debdb9bf9da706fdf414e8bcac7", + "size": 8924 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/messages", + "status": "success", + "path": "en/api/ruby/messages.md", + "sha256": "757af1306959b9337aac7331c0584869076ce2037995c4170b40231ba454815e", + "size": 820024 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/messages/create", + "status": "success", + "path": "en/api/ruby/messages/create.md", + "sha256": "e64c5e94b9c0080e3091f336b4e30de11cece234289d442fe4f3615bafd5a7fa", + "size": 111944 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/messages/count_tokens", + "status": "success", + "path": "en/api/ruby/messages/count_tokens.md", + "sha256": "0e36c1795af358eb5c45ccae6c5919e8ee202b9fe83949944764fad4485985b9", + "size": 88261 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches", + "status": "success", + "path": "en/api/ruby/messages/batches.md", + "sha256": "4644de0fabb88393a14ecdf5bc9801c3803cbec988889beab6683b7f0b01253f", + "size": 219391 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches/create", + "status": "success", + "path": "en/api/ruby/messages/batches/create.md", + "sha256": "9fe7e3f190d2341b28e3796ced6135abf21b9d1e6696ec7c587d4f3f36e145b8", + "size": 102587 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches/retrieve", + "status": "success", + "path": "en/api/ruby/messages/batches/retrieve.md", + "sha256": "2792a2109abb099151501bf269e767895dc3e80e1d8a8362cb73367ee34b6948", + "size": 3469 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches/list", + "status": "success", + "path": "en/api/ruby/messages/batches/list.md", + "sha256": "a51fbb8269d344d6ddcf0f92c4b2a5849e94a4fde37714cf83fc7a5254262e61", + "size": 3663 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches/cancel", + "status": "success", + "path": "en/api/ruby/messages/batches/cancel.md", + "sha256": "c95b6e6aab5e4af187c2e0060fdcfecc71acd179499bf1b56c8e0c3b78db9b1f", + "size": 3781 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches/delete", + "status": "success", + "path": "en/api/ruby/messages/batches/delete.md", + "sha256": "58810ae26925e085742e6cc18a21a0c5b45ad8de4cea42d7828dfb3ff0a97e7f", + "size": 980 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches/results", + "status": "success", + "path": "en/api/ruby/messages/batches/results.md", + "sha256": "c127ce7e2b4abbb080cc040fae881c83aaa462b369b6d2ce4bfd4a32c63c8160", + "size": 26893 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/models", + "status": "success", + "path": "en/api/ruby/models.md", + "sha256": "34a791f60893cf93855d6fbeda27da226a91ba6968bbd24710d4fa72abcd5fa3", + "size": 22229 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/models/list", + "status": "success", + "path": "en/api/ruby/models/list.md", + "sha256": "a9ec01ef83c2e2aeecd30ff83558f9e702ef0ad0faef6e08fa968334fd170a41", + "size": 6029 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/models/retrieve", + "status": "success", + "path": "en/api/ruby/models/retrieve.md", + "sha256": "b458095d57e2abe4e69543d578c25a37d32dfb695eb19b84f90cf032ac73e653", + "size": 5700 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta", + "status": "success", + "path": "en/api/ruby/beta.md", + "sha256": "3f0457677f93da510b856229b3b5d5dfc72da4df6fdfe5a6c93b23c0e89d7780", + "size": 1599144 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/models", + "status": "success", + "path": "en/api/ruby/beta/models.md", + "sha256": "9591a2161e4be1ef29617b47f82208a19a39ca65a4ed711b619ddb6acd1c781b", + "size": 22702 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/models/list", + "status": "success", + "path": "en/api/ruby/beta/models/list.md", + "sha256": "6650a1dd1bfcdb8e80832e9c5a3b4c287772fc464e607d7ebdcabe1e02dd5e9a", + "size": 6127 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/models/retrieve", + "status": "success", + "path": "en/api/ruby/beta/models/retrieve.md", + "sha256": "b72ff648c7433ea6170ffd7f5daca8e0aa35d6702743a2af45b734c1ab4ef1b2", + "size": 5808 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages", + "status": "success", + "path": "en/api/ruby/beta/messages.md", + "sha256": "f9bcba1814fa5ab8e27248220cb6b40fc092606d36b3ee93e1adc2ed6aead3ff", + "size": 1014123 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/create", + "status": "success", + "path": "en/api/ruby/beta/messages/create.md", + "sha256": "f35ca366f2c805b3266b4f17e1d1e2709852f787696306309b155dcfed6d5c67", + "size": 140523 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/count_tokens", + "status": "success", + "path": "en/api/ruby/beta/messages/count_tokens.md", + "sha256": "0e232501f3e1c9425fef3c92b3caf6d5623bed1b8df50a9d9d69376ec221c476", + "size": 108814 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches", + "status": "success", + "path": "en/api/ruby/beta/messages/batches.md", + "sha256": "e656db963a6096c131d2b89977beeaa5332f823f6763b4210ba08fc4460c5bf1", + "size": 281327 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches/create", + "status": "success", + "path": "en/api/ruby/beta/messages/batches/create.md", + "sha256": "418a307d4abd91292e2958101116e79b7268d34ba651b24844431c8f1461e160", + "size": 125151 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches/retrieve", + "status": "success", + "path": "en/api/ruby/beta/messages/batches/retrieve.md", + "sha256": "37d7ef9101ea4125d2fadd0026a1c4a68ed2c3dfa0e3d231b6b4713cded42ae6", + "size": 4520 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches/list", + "status": "success", + "path": "en/api/ruby/beta/messages/batches/list.md", + "sha256": "bc2e47acd7e8720cbd2ecb4fb0922189a42a6d9ac673666894c79732a7880534", + "size": 4694 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches/cancel", + "status": "success", + "path": "en/api/ruby/beta/messages/batches/cancel.md", + "sha256": "25aad8cfbf8a9da7c9ca64195ed67eb95711869ed0d1f8f7885d6284f9e0e66e", + "size": 4832 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches/delete", + "status": "success", + "path": "en/api/ruby/beta/messages/batches/delete.md", + "sha256": "7a1d5737c3446c87021ac739e45e1c51f5d189574ffd2dbfa57b43d63f4dcc75", + "size": 2027 + }, + { + "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches/results", + "status": "success", + "path": "en/api/ruby/beta/messages/batches/results.md", + "sha256": "7f45fa4d84cbc872c5b3039b9e1b8ee9d77eabdf2ebcd03382f2d4ee5981a303", + "size": 36691 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/files/retrieve_metadata", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/agents", "status": "success", - "path": "en/api/typescript/beta/files/retrieve_metadata.md", - "sha256": "e582dbb4eab92d5457f947360014927a60fe5a50609f0d4fd91caceb6fce3b11", - "size": 2253 + "path": "en/api/ruby/beta/agents.md", + "sha256": "79a0598e7f8b5820a286d681ef45b0f6f100638a1c0a93527b5e761088da2116", + "size": 98651 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/files/delete", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/agents/create", "status": "success", - "path": "en/api/typescript/beta/files/delete.md", - "sha256": "7cac6a05c2eac6a556945b2c207c41f48761a8a5b4b32ad4992e5b19b1e2715d", - "size": 1831 + "path": "en/api/ruby/beta/agents/create.md", + "sha256": "87c9767940c103c9055d3090bf6e8da6faa265e1c5dcd034e57c59a7c755f292", + "size": 17909 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/agents/list", "status": "success", - "path": "en/api/typescript/beta/skills.md", - "sha256": "4e8f14b094682f9b5ed8b058bc784aaeb4bf577dd60611c2ccd95df846d9cee7", - "size": 28316 + "path": "en/api/ruby/beta/agents/list.md", + "sha256": "99698b878b6c561ec3b337021b931f808e578ca18e5fe22b900886035bb35009", + "size": 8415 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/create", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/agents/retrieve", "status": "success", - "path": "en/api/typescript/beta/skills/create.md", - "sha256": "e0eeb1db457cd6362c5732fa13de6f6bfc91f6a26006ad6c6fa7b8b6681d31b3", - "size": 2867 + "path": "en/api/ruby/beta/agents/retrieve.md", + "sha256": "9c32ed5861bedcd0dbf01a3cbb2a560c7674109795083a5650d244658b9ecf8c", + "size": 8234 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/list", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/agents/update", "status": "success", - "path": "en/api/typescript/beta/skills/list.md", - "sha256": "000f1ce237972c0d27d6b6183dc5949947b4843331104040c59fe5aaf8b5e474", - "size": 3144 + "path": "en/api/ruby/beta/agents/update.md", + "sha256": "2660beec3953d2c0ce2583c058bc256888bd68bb36ad95b2f4c1fbc7340eb712", + "size": 18545 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/retrieve", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/agents/archive", "status": "success", - "path": "en/api/typescript/beta/skills/retrieve.md", - "sha256": "b5a93189097faadfd629e603b673ff7c735adb9cf750c0c80ec49ecd6462e929", - "size": 2630 + "path": "en/api/ruby/beta/agents/archive.md", + "sha256": "d30bb9c8017f91e3e9529e3305d43bebd7bd70e6f2c9c0bc543d204cc4bf0e0d", + "size": 8137 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/delete", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/agents/versions", "status": "success", - "path": "en/api/typescript/beta/skills/delete.md", - "sha256": "c2ef5cd187a7ed2cd0081bf5109518b985f2a1952b03e78767ed15015ef9b094", - "size": 1942 + "path": "en/api/ruby/beta/agents/versions.md", + "sha256": "a26051b2f28de391d198af11cbc70f214654612498b465f539214a75eebd926b", + "size": 8255 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/versions", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/agents/versions/list", "status": "success", - "path": "en/api/typescript/beta/skills/versions.md", - "sha256": "22f8450eb84a5d0421309929a23dc677ac45d5dfd6256c50b122f00d39923839", - "size": 14618 + "path": "en/api/ruby/beta/agents/versions/list.md", + "sha256": "b916e48a62841a1173bb6c3627c5673f96ca7dfe2bebefab139231f88974d1cf", + "size": 8243 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/versions/create", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/environments", "status": "success", - "path": "en/api/typescript/beta/skills/versions/create.md", - "sha256": "bc59c6ab0a4ebee2410b843a491910862b57518bfa02076d38b33ab7f7998519", - "size": 2957 + "path": "en/api/ruby/beta/environments.md", + "sha256": "c1acab4aaee716baf46e2c369c8ae4bd7448c81d9730a280ff5b5687240de689", + "size": 34318 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/versions/list", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/environments/create", "status": "success", - "path": "en/api/typescript/beta/skills/versions/list.md", - "sha256": "156005e2ac083058987d298a02a646a8baed9e443ecce3bfc51de2fa5717d397", - "size": 3075 + "path": "en/api/ruby/beta/environments/create.md", + "sha256": "ecc151688c29d8da0b04f83f2da3260555ae0004773f55d073d268d425fb92b0", + "size": 5991 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/versions/retrieve", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/environments/list", "status": "success", - "path": "en/api/typescript/beta/skills/versions/retrieve.md", - "sha256": "bc1d1cea1e728474cb47c462248e26ee68a0054833c6c4fee2d3a46493bddf1a", - "size": 2955 + "path": "en/api/ruby/beta/environments/list.md", + "sha256": "beb4e9f70607fe567768a2fbd2e89a4366f60968e937fdc23ed375e83e334004", + "size": 3929 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/skills/versions/delete", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/environments/retrieve", "status": "success", - "path": "en/api/typescript/beta/skills/versions/delete.md", - "sha256": "c6fdb5801d1a6b3195e3a5387d63bd6a2bf2c6d4c103f52ffb5654917f2968f5", - "size": 2245 + "path": "en/api/ruby/beta/environments/retrieve.md", + "sha256": "a3385edee7398c69267ae2589349d827e3fa490d17ee03609b7e30589f9beb65", + "size": 3772 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/user_profiles", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/environments/update", "status": "success", - "path": "en/api/typescript/beta/user_profiles.md", - "sha256": "3ad2a44879e7dd5c6b1844312edd2ec0eeee0d1ae87758d44d257f4232fec00b", - "size": 11474 + "path": "en/api/ruby/beta/environments/update.md", + "sha256": "cbd44a41ac5ef8ccd57dd5733b4b0c6a8c2544a9be90540097cbf2c329418209", + "size": 6091 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/user_profiles/create", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/environments/delete", "status": "success", - "path": "en/api/typescript/beta/user_profiles/create.md", - "sha256": "fb063f616bc8da71754117172860dcc0484624ab0a7f2e070d3fa852defa7767", - "size": 2251 + "path": "en/api/ruby/beta/environments/delete.md", + "sha256": "495c1b50050a3790b765ae1ef2de8e3def30fa0fff4694cd8b8ba870ed660752", + "size": 1758 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/user_profiles/list", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/environments/archive", "status": "success", - "path": "en/api/typescript/beta/user_profiles/list.md", - "sha256": "22cece3a2f52b2db49abc45d69f5ff84996fcd2b6fa31955ede5bd4a5cc89b3a", - "size": 2267 + "path": "en/api/ruby/beta/environments/archive.md", + "sha256": "38de126bae003431e76caf3d0c93aa39abed2af3216039d418893f30ba8c63cb", + "size": 3830 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/user_profiles/retrieve", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions", "status": "success", - "path": "en/api/typescript/beta/user_profiles/retrieve.md", - "sha256": "e016ebb736cae7a8515daf853f95bb6f362bbe927e1c905a8819dff0a5560c3c", - "size": 1999 + "path": "en/api/ruby/beta/sessions.md", + "sha256": "1e917b22c760e15be0a366afe256d61c49a0fb4c4d4a5f9e1f8aff43043d7b5a", + "size": 331279 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/user_profiles/update", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/create", "status": "success", - "path": "en/api/typescript/beta/user_profiles/update.md", - "sha256": "525eaa21bc2232ac6725a7979a2bc123bd3a3737b5831999471fa632aa68c994", - "size": 2376 + "path": "en/api/ruby/beta/sessions/create.md", + "sha256": "c1cbba609a241300bf822b73d8423ebae0ce819ec4d6926f09ae9b02106a4f5c", + "size": 13500 }, { - "url": "https://platform.claude.com/docs/en/api/typescript/beta/user_profiles/create_enrollment_url", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/list", "status": "success", - "path": "en/api/typescript/beta/user_profiles/create_enrollment_url.md", - "sha256": "e3a89df43ea995924e93a200ee8ab9e8fb7bfe5fe28a1c55c185cec7e0a1f14a", - "size": 1914 + "path": "en/api/ruby/beta/sessions/list.md", + "sha256": "870ee171e4d5cd6281ad531c3b8d72c75eb29e2b7ab5192e03895cc3c0abb5e8", + "size": 11829 }, { - "url": "https://platform.claude.com/docs/en/api/python/completions", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/retrieve", "status": "success", - "path": "en/api/python/completions.md", - "sha256": "7d9e0f7b0bdccc3d6018c5ae4ef9a5b79b72d8315968d3d7bffaffdeb574aeab", - "size": 15442 + "path": "en/api/ruby/beta/sessions/retrieve.md", + "sha256": "60772995115323962578b4d839346c444dadb579741a5cb194d89841efb4c40d", + "size": 11064 }, { - "url": "https://platform.claude.com/docs/en/api/python/completions/create", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/update", "status": "success", - "path": "en/api/python/completions/create.md", - "sha256": "a6d5ed3b0d58b1a6a104c9dd331a774433d8d1fdd4e5c29043d83553d4863992", - "size": 11565 + "path": "en/api/ruby/beta/sessions/update.md", + "sha256": "38de0608faf138c0d3b27b22e169a8843a475a77ec65f1bc02967eef6f3d3aa0", + "size": 11423 }, { - "url": "https://platform.claude.com/docs/en/api/python/messages", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/delete", "status": "success", - "path": "en/api/python/messages.md", - "sha256": "6d2228f3767cc55c4d6d381fa00a2fbb81b1e8aec7f6061480d69b9c2e6b26c2", - "size": 867414 + "path": "en/api/ruby/beta/sessions/delete.md", + "sha256": "ab67f391e596295f69ffc455092ac6c442d4620a99d92b6e7320d70f91639a2b", + "size": 1649 }, { - "url": "https://platform.claude.com/docs/en/api/python/messages/create", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/archive", "status": "success", - "path": "en/api/python/messages/create.md", - "sha256": "89d7762d3c783b56a9759e2e93002294de6724d0c98be9627b7ae9eead11b5e7", - "size": 119329 + "path": "en/api/ruby/beta/sessions/archive.md", + "sha256": "3153b52ebae57002df1d7474662dbf363be7ee61ea4fd079f97c70908203128d", + "size": 11074 }, { - "url": "https://platform.claude.com/docs/en/api/python/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/events", "status": "success", - "path": "en/api/python/messages/count_tokens.md", - "sha256": "6bb99cfc051c268b3bcfd5362c9016559b6201123e49d1434abd74e3312e226d", - "size": 93904 + "path": "en/api/ruby/beta/sessions/events.md", + "sha256": "b0d44151857e7b2963bdbbef7072b14d87561c87133fe128d1ffd226b2c940f3", + "size": 233821 }, { - "url": "https://platform.claude.com/docs/en/api/python/messages/batches", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/events/list", "status": "success", - "path": "en/api/python/messages/batches.md", - "sha256": "8a2128ab4986ebecff44b11ff506d7abae32c1b7e311009b0222bea91f8d9436", - "size": 233317 + "path": "en/api/ruby/beta/sessions/events/list.md", + "sha256": "dbcc40c66b056cc2d82255f1f835443b1392fa6f6649d02961950aa4cf271c11", + "size": 35594 }, { - "url": "https://platform.claude.com/docs/en/api/python/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/events/send", "status": "success", - "path": "en/api/python/messages/batches/create.md", - "sha256": "62852e117b399d73da052d7f0f610f5924dac0462ba3e28c333df2795998239f", - "size": 108471 + "path": "en/api/ruby/beta/sessions/events/send.md", + "sha256": "4564ce9e2f53c58a797dd60aca2a5c796a0690584837c20c5aeb2516d3987ac2", + "size": 19477 }, { - "url": "https://platform.claude.com/docs/en/api/python/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/events/stream", "status": "success", - "path": "en/api/python/messages/batches/retrieve.md", - "sha256": "0d277d480739f911ab4376e600949bf82f01633bc39154d07f28846a77d72010", - "size": 3609 + "path": "en/api/ruby/beta/sessions/events/stream.md", + "sha256": "59770b32002a12a99879e0fb98a928489161f539694b82db0dddca44f6cdd458", + "size": 35411 }, { - "url": "https://platform.claude.com/docs/en/api/python/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/resources", "status": "success", - "path": "en/api/python/messages/batches/list.md", - "sha256": "6de85ce7f5d2a44c1d8e815a67e552cc88ce58aea737221c67e614905d46ebc9", - "size": 3857 + "path": "en/api/ruby/beta/sessions/resources.md", + "sha256": "e747dd0b8d364b3f5db169ffc32080489aa0358e373e61631213e78676437085", + "size": 16968 }, { - "url": "https://platform.claude.com/docs/en/api/python/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/resources/add", "status": "success", - "path": "en/api/python/messages/batches/cancel.md", - "sha256": "17492c90948f23ad1f8ad17d33ab20e32d1bf14c9b65da102827a8e31ce7f79c", - "size": 3921 + "path": "en/api/ruby/beta/sessions/resources/add.md", + "sha256": "82b170778df0bf88f9b0b7389a57a560b35a33a1b1b70b96e844b145e762194c", + "size": 2003 }, { - "url": "https://platform.claude.com/docs/en/api/python/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/resources/list", "status": "success", - "path": "en/api/python/messages/batches/delete.md", - "sha256": "74cd4bbe006b91b26d57aac7a654f489294abe32b24f440a8465c45cb3977acf", - "size": 1070 + "path": "en/api/ruby/beta/sessions/resources/list.md", + "sha256": "685a56abc4afb749450d6ab580429fe9aa5b94cce4904d4009b9b9072a875ef1", + "size": 2769 }, { - "url": "https://platform.claude.com/docs/en/api/python/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/resources/retrieve", "status": "success", - "path": "en/api/python/messages/batches/results.md", - "sha256": "58be8ffb4c6a2bc1d15287f5211d2eef049daa068139eb19f9a17bda135c3020", - "size": 28816 + "path": "en/api/ruby/beta/sessions/resources/retrieve.md", + "sha256": "2970c33d50a71180f6ee07b0276f6d6bde9545dcc4d6ace493f62810233689e3", + "size": 2691 }, { - "url": "https://platform.claude.com/docs/en/api/python/models", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/resources/update", "status": "success", - "path": "en/api/python/models.md", - "sha256": "09f716822cdf4b1bbef632c88a19c0ca27043d50a363fe2618ebf0a6e56d10a2", - "size": 22811 + "path": "en/api/ruby/beta/sessions/resources/update.md", + "sha256": "150c11064db9daaeb29eaa5d147cdac51b9164f99a957f029e434b3a6d2a6ebc", + "size": 2873 }, { - "url": "https://platform.claude.com/docs/en/api/python/models/list", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/sessions/resources/delete", "status": "success", - "path": "en/api/python/models/list.md", - "sha256": "a9dac0f74d273aec3a9a8bbb901c523ac07469377056fbab4c6bedc61af7ab7a", - "size": 6255 + "path": "en/api/ruby/beta/sessions/resources/delete.md", + "sha256": "ceaa41502010f433016242edbfff9a722f8934b10c5061ba9105d2325d93891b", + "size": 1804 }, { - "url": "https://platform.claude.com/docs/en/api/python/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults", "status": "success", - "path": "en/api/python/models/retrieve.md", - "sha256": "cd8844a34c43c65c0ec327b126350fb92e0f5e0829c971ce798a4914e1e6ef0f", - "size": 5900 + "path": "en/api/ruby/beta/vaults.md", + "sha256": "8bf32f23379e1f0e3d3ac04fe08ac04790cc76a84813bd21cf1c7a4569eb1510", + "size": 56006 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/create", "status": "success", - "path": "en/api/python/beta.md", - "sha256": "bf661345da428258d1713754258e4898d6888dd7786b610e91dd24ff37a060de", - "size": 1141294 + "path": "en/api/ruby/beta/vaults/create.md", + "sha256": "8c12f96d5d753a74fc8e39adb41dfa9702deaabd5788960ef4a0fe6837bc2aec", + "size": 2093 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/models", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/list", "status": "success", - "path": "en/api/python/beta/models.md", - "sha256": "25b6631528efcfa7947a4e0de005a8aedff680b80f1197dd7b114323e23f7939", - "size": 23284 + "path": "en/api/ruby/beta/vaults/list.md", + "sha256": "cd972eb2a71e6f41a43d00c665bd24f8ef4667de09f3f7d21c17b2055bb609fd", + "size": 2114 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/models/list", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/retrieve", "status": "success", - "path": "en/api/python/beta/models/list.md", - "sha256": "eb4ad02e164fc363b195e84b0e012efcf2ec0b4846bc8d490e92e79a164f0c7d", - "size": 6353 + "path": "en/api/ruby/beta/vaults/retrieve.md", + "sha256": "6ea90fae5fe575670fa8af58fd98ce3268c65af2d6a2745cd15b914caedc083d", + "size": 1965 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/update", "status": "success", - "path": "en/api/python/beta/models/retrieve.md", - "sha256": "fb5634f9e0bdb64b252e172bc5e5793576b167800eb6156bfc9025791e0224dc", - "size": 6008 + "path": "en/api/ruby/beta/vaults/update.md", + "sha256": "3369c3f7baf0bc9b9f2dff356f07d9ff7aeae181a210d33393679e0cc5e722be", + "size": 2197 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/messages", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/delete", "status": "success", - "path": "en/api/python/beta/messages.md", - "sha256": "9af1ad1a19bf2a258ce86fb4f96ce17882a46338658226477df00a9bb7d7c355", - "size": 1064660 + "path": "en/api/ruby/beta/vaults/delete.md", + "sha256": "07d740133e1e2123a76036d6b62c3f4e2a3de591fa71f84d02e1c9713cb5042b", + "size": 1640 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/messages/create", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/archive", "status": "success", - "path": "en/api/python/beta/messages/create.md", - "sha256": "a24c4e1befe9e9da1a7574ef52ad9720bccb1a7ed2e84c493529993b637f59c6", - "size": 149045 + "path": "en/api/ruby/beta/vaults/archive.md", + "sha256": "60a764ee80d38ea0b939a262d09ef6cae9664cb25e3789daa90ac72d21c14869", + "size": 1975 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/credentials", "status": "success", - "path": "en/api/python/beta/messages/count_tokens.md", - "sha256": "2ada295308b73bc56ca9c5d29dfdbe667296923adb76612e8084d31c7b4150af", - "size": 115275 + "path": "en/api/ruby/beta/vaults/credentials.md", + "sha256": "951515aeec60d7f49eda47ad4e4d56840ef577edba1d1ed6562dc9de9b773d80", + "size": 43187 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/credentials/create", "status": "success", - "path": "en/api/python/beta/messages/batches.md", - "sha256": "d177901d881f2aa11d7d3d6b74f800d2aa994a3563e2864d848e4c9db69796af", - "size": 296985 + "path": "en/api/ruby/beta/vaults/credentials/create.md", + "sha256": "8526c8c88c5c309250b152a70963c1c0d03e68522354a19b2867266ab94f5d97", + "size": 6921 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/credentials/list", "status": "success", - "path": "en/api/python/beta/messages/batches/create.md", - "sha256": "fda5bebd8d3c6f233a593773af1619e26fe6a8058ba9611a1e3a3aa9d165a1cd", - "size": 132101 + "path": "en/api/ruby/beta/vaults/credentials/list.md", + "sha256": "71635b32193df68726b26734703c7320655bdc706b0fc88e2e82dbd975e7c085", + "size": 4478 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/credentials/retrieve", "status": "success", - "path": "en/api/python/beta/messages/batches/retrieve.md", - "sha256": "e64fee6dfb88bb40186c4964dcd87b194ae481a7a501294c9aae1236f80e2236", - "size": 4725 + "path": "en/api/ruby/beta/vaults/credentials/retrieve.md", + "sha256": "7b6588026a34f98b4114656d5aca6399969f9e8f8a5ee1a0bc1e1e1c1e639220", + "size": 4346 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/credentials/update", "status": "success", - "path": "en/api/python/beta/messages/batches/list.md", - "sha256": "334d1f6983f58d27e2978584e8f1d6a7f9fc199bfe4921b8adbab00b0ee36a73", - "size": 4917 + "path": "en/api/ruby/beta/vaults/credentials/update.md", + "sha256": "2efc2746f0cfd04d7a7e47e6cf2e853ac4c5e87e8feffac1bda1b31fed0b4bb8", + "size": 6425 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/credentials/delete", "status": "success", - "path": "en/api/python/beta/messages/batches/cancel.md", - "sha256": "9597153ad24ffcd0e595f341cffbc8dc71f76bfbdf485f2e698c81099d520c20", - "size": 5035 + "path": "en/api/ruby/beta/vaults/credentials/delete.md", + "sha256": "8acf4d9b94998b7ed1469dd6222e6e232cc726f57ced03bb19a88b55494df545", + "size": 1830 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/vaults/credentials/archive", "status": "success", - "path": "en/api/python/beta/messages/batches/delete.md", - "sha256": "9164efd8d3df730ed6ab5dbb09e50d084c09ed20c338e80552f5ad9b8dc0efa5", - "size": 2180 + "path": "en/api/ruby/beta/vaults/credentials/archive.md", + "sha256": "c628cf3c921b595c115fb79fe6c363abcb4aa89aab482c8a93d7acd7c016fcd7", + "size": 4356 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/files", "status": "success", - "path": "en/api/python/beta/messages/batches/results.md", - "sha256": "c4c33ae312c60a4a362cae87ea049f092ec9517e4039fc2defd3b9a139efb0ee", - "size": 38770 + "path": "en/api/ruby/beta/files.md", + "sha256": "ccbc639c3730eef75812ec99408a7a60d2f2e24d451217890333b46e5c3061a7", + "size": 11518 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/files", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/files/upload", "status": "success", - "path": "en/api/python/beta/files.md", - "sha256": "1340804bc87f66ac44bb739f0ac60dd4a55ea6f375eedbe020706b4a53575d0d", - "size": 10858 + "path": "en/api/ruby/beta/files/upload.md", + "sha256": "8aaa9b2c3dd49231899a1364367246f1242c1af82550da9c9ec4e8c763428125", + "size": 2245 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/files/upload", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/files/list", "status": "success", - "path": "en/api/python/beta/files/upload.md", - "sha256": "a825a89332f9da3970b5dceae3a3838d914f18b25f4e3fc81ac1a3ff65e5d4bc", - "size": 2078 + "path": "en/api/ruby/beta/files/list.md", + "sha256": "ab35b44f5e6a0b984cf17d6bf1aefd805149c9586576559e93c61b3085a5177c", + "size": 2682 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/files/list", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/files/download", "status": "success", - "path": "en/api/python/beta/files/list.md", - "sha256": "5cf946fa05f1e7c5b8009eba25016bd47fe58e619f85965d4fe09e9e490454b6", - "size": 2441 + "path": "en/api/ruby/beta/files/download.md", + "sha256": "2ce6e08b5748e5919a091e616fb2fd708d9ad99b5dd9dffb0abc4d8f7a539ea3", + "size": 1395 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/files/download", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/files/retrieve_metadata", "status": "success", - "path": "en/api/python/beta/files/download.md", - "sha256": "d749f9f5e073fe464d703fb744ef3bad631f38fd8f63d49a6614460ebd564691", - "size": 1591 + "path": "en/api/ruby/beta/files/retrieve_metadata.md", + "sha256": "3b94dd6f947947acdd59b66536f363f15af354c8b61be6d50be0b9d40ed6129b", + "size": 2277 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/files/retrieve_metadata", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/files/delete", "status": "success", - "path": "en/api/python/beta/files/retrieve_metadata.md", - "sha256": "2dee0f5a621a6cf0381ff736e080afdbe8774ff575d42fe99a8ee675fae007dc", - "size": 2139 + "path": "en/api/ruby/beta/files/delete.md", + "sha256": "be2dedb313867db41482ffb1f44c27cec0a0018810ff740decf6d3ac080c024e", + "size": 1582 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/files/delete", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills", "status": "success", - "path": "en/api/python/beta/files/delete.md", - "sha256": "2c7f56ba4582bf4aa150c7468f6e051db7d51db5f26dbf9a7166b8d8b967536a", - "size": 1735 + "path": "en/api/ruby/beta/skills.md", + "sha256": "a1aa7504520cb79853df6b84d4e6c7fb9d6448681effd77c9b0b27f669c361aa", + "size": 25752 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/skills", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/create", "status": "success", - "path": "en/api/python/beta/skills.md", - "sha256": "5f8a903d4e8e42053c6fbbdb2b3e9ee70d25b783c05aadbe525e9a0fd207fc6b", - "size": 26812 + "path": "en/api/ruby/beta/skills/create.md", + "sha256": "de0032b23f239c592eb3ccaa350779269259b91d7e5abd0eb0c66ca7fd1a5290", + "size": 2535 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/skills/create", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/list", "status": "success", - "path": "en/api/python/beta/skills/create.md", - "sha256": "d2efeafa149a06a154bc6e254872339dd99f898917f4b7ac1c2fae7f6105ddad", - "size": 2680 + "path": "en/api/ruby/beta/skills/list.md", + "sha256": "815332cf94cc75a0d16758e3a3587dc853d6c765f9a1c95d5220aaf65047be51", + "size": 2711 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/skills/list", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/retrieve", "status": "success", - "path": "en/api/python/beta/skills/list.md", - "sha256": "c4ebd42c04f780a128205df33e29e95c658a11ea08ca2bde53f3b3656b0ff9b1", - "size": 2875 + "path": "en/api/ruby/beta/skills/retrieve.md", + "sha256": "72ad936c5d18bbfc73421035e76f171e33a121079e0d50a5e64b21f0a73115bf", + "size": 2362 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/skills/retrieve", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/delete", "status": "success", - "path": "en/api/python/beta/skills/retrieve.md", - "sha256": "ae33c90427d1b975db5f7ea345dad30bd1425889410e5c43378c3edd02c071eb", - "size": 2500 + "path": "en/api/ruby/beta/skills/delete.md", + "sha256": "81cb6d58d9a8bb91fa235a9677c062f8d14f430318f5e63ae271bdf68d5c1db2", + "size": 1692 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/skills/delete", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/versions", "status": "success", - "path": "en/api/python/beta/skills/delete.md", - "sha256": "35e74b9c89f37406053f2932ee15abebe2ddc9ab717d0e7ff38d32bdb860d79c", - "size": 1823 + "path": "en/api/ruby/beta/skills/versions.md", + "sha256": "91fed1ceda2af1b9a51aa4e8aa6fd3293eaabd505b79193a87f5a5538cc34cd1", + "size": 13355 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/skills/versions", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/versions/create", "status": "success", - "path": "en/api/python/beta/skills/versions.md", - "sha256": "35db706d65535f789f0260d1a5a50f891bd7563ac8263549726feef26bd3f9b9", - "size": 13826 + "path": "en/api/ruby/beta/skills/versions/create.md", + "sha256": "e299e7412322d06e068a53d90d7a2d41d0bb01a7d34dfe6608efc4b0d503de22", + "size": 2659 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/skills/versions/create", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/versions/list", "status": "success", - "path": "en/api/python/beta/skills/versions/create.md", - "sha256": "2add11e637f68875c3e055878fdba0e5a7218eb4142b3e89c54f2ffb70a47c6f", - "size": 2790 + "path": "en/api/ruby/beta/skills/versions/list.md", + "sha256": "a414866805c8c81aa81067c274babf9309840b3926a22b301d2d7fd92cd46f40", + "size": 2672 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/skills/versions/list", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/versions/retrieve", "status": "success", - "path": "en/api/python/beta/skills/versions/list.md", - "sha256": "97ca5d6d566293ef6da1c0544ee3ff7f82a6ed9f0364dadc92c527ad8a485910", - "size": 2822 + "path": "en/api/ruby/beta/skills/versions/retrieve.md", + "sha256": "284bf501f80f88d65dd99c6e1fcfd1304f1dcb39dcd5ca0f2bb5b01ab2d75051", + "size": 2660 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/skills/versions/retrieve", + "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/versions/delete", "status": "success", - "path": "en/api/python/beta/skills/versions/retrieve.md", - "sha256": "6d3e2e6c054b2adf3e4b37ffc6893d01dfd548d884e15f6446f6b2811004cb73", - "size": 2776 + "path": "en/api/ruby/beta/skills/versions/delete.md", + "sha256": "fd7196f1136264ac149b7c3abb736a3d5f2c3b085a8af4ad657d41484531e3db", + "size": 1954 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/skills/versions/delete", + "url": "https://platform.claude.com/docs/en/api/terraform/completions", "status": "success", - "path": "en/api/python/beta/skills/versions/delete.md", - "sha256": "85eee7f9031f994b58ca91deb5f70ca749111ae810f65a1502d9eaafbe6cf217", - "size": 2086 + "path": "en/api/terraform/completions.md", + "sha256": "2b756a0777bfb16bc59dc5c06bf703edf1b26477cdb3a4669291e7e8deabbc8b", + "size": 89206 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/user_profiles", + "url": "https://platform.claude.com/docs/en/api/terraform/completions/create", "status": "success", - "path": "en/api/python/beta/user_profiles.md", - "sha256": "336b13663820ea5e051ad2091b66bd515f821600932a790bbd3737cdeb14c297", - "size": 10589 + "path": "en/api/terraform/completions/create.md", + "sha256": "7f95d3e916c72d62ba13cf18a5337ec59d1b1517ecf7be24c61da80e3c66e5a0", + "size": 89231 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/user_profiles/create", + "url": "https://platform.claude.com/docs/en/api/terraform/messages", "status": "success", - "path": "en/api/python/beta/user_profiles/create.md", - "sha256": "93f69bbec96df09274185dda11a57a2f0ada14cc0149b6087acee0f57b5b48ff", - "size": 2060 + "path": "en/api/terraform/messages.md", + "sha256": "3bf3ca082016f234f52962b9fda7d32f88ff4b542a8bb000600f4b548f8b9d91", + "size": 89197 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/user_profiles/list", + "url": "https://platform.claude.com/docs/en/api/terraform/messages/create", "status": "success", - "path": "en/api/python/beta/user_profiles/list.md", - "sha256": "6b63681ced10ed5826d4fafa4b5f1ec3c2310af912e535f0f7922e8baad65ca9", - "size": 2025 + "path": "en/api/terraform/messages/create.md", + "sha256": "fb9d8382f7d45722f6350e60b47abf737842dac3d8519849ab1fc741fbdd6eb0", + "size": 89222 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/user_profiles/retrieve", + "url": "https://platform.claude.com/docs/en/api/terraform/messages/count_tokens", "status": "success", - "path": "en/api/python/beta/user_profiles/retrieve.md", - "sha256": "11905b3075f3836f3dc34934fff883915a9151c8293257fa2ba91913a88a99f6", - "size": 1857 + "path": "en/api/terraform/messages/count_tokens.md", + "sha256": "6b436d7067f400849c44a7eccd1543372cef0764fd29076697f677227091a69d", + "size": 89240 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/user_profiles/update", + "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches", "status": "success", - "path": "en/api/python/beta/user_profiles/update.md", - "sha256": "ea5373607ed6c032b7f89181b274a12ea43668abd402227b6e3bdb97bfa753db", - "size": 2189 + "path": "en/api/terraform/messages/batches.md", + "sha256": "4e7934b4a578205f4b439d30a060aa3196e0ce7067176407d5f719e431a53de7", + "size": 89225 }, { - "url": "https://platform.claude.com/docs/en/api/python/beta/user_profiles/create_enrollment_url", + "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches/create", "status": "success", - "path": "en/api/python/beta/user_profiles/create_enrollment_url.md", - "sha256": "28aa9359e5a53bbe77db1a6d835944481e0b0fa5feb75400d1f65fcaabb818a4", - "size": 1784 + "path": "en/api/terraform/messages/batches/create.md", + "sha256": "157c7399b51348c5ad35f4d1297ac5558b2b03c72df0fc6f20c08b67fb24f222", + "size": 89250 }, { - "url": "https://platform.claude.com/docs/en/api/java/completions", + "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches/retrieve", "status": "success", - "path": "en/api/java/completions.md", - "sha256": "094172215ca0cb3be34c83e0127af8c95363c63365eb4ba55f5f2f2ee055b354", - "size": 10463 + "path": "en/api/terraform/messages/batches/retrieve.md", + "sha256": "0efa8455f01ab5cfaea378507b87b444ce7df05048d4b9c5fe0c299ea17caebc", + "size": 89256 }, { - "url": "https://platform.claude.com/docs/en/api/java/completions/create", + "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches/list", "status": "success", - "path": "en/api/java/completions/create.md", - "sha256": "fd3bff7322dc0f78c98c160e80ffdc895a1cce5722362fd02760ffa83128e855", - "size": 7908 + "path": "en/api/terraform/messages/batches/list.md", + "sha256": "8eacf0355fe7640018ce6965fd0f2e9b45bf154a224b0d7d287558dd0ec89b94", + "size": 89244 }, { - "url": "https://platform.claude.com/docs/en/api/java/messages", + "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches/cancel", "status": "success", - "path": "en/api/java/messages.md", - "sha256": "f2c77cd02fceec0065b341846e2620ec610a56c4054abe61b142feed2d3def48", - "size": 919087 + "path": "en/api/terraform/messages/batches/cancel.md", + "sha256": "6dd0e24143bd68aa38109f8261037715327c4d8a1e250ac98fdecbbd49468e82", + "size": 89250 }, { - "url": "https://platform.claude.com/docs/en/api/java/messages/create", + "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches/delete", "status": "success", - "path": "en/api/java/messages/create.md", - "sha256": "31053f1e246ece648883755c5d493da0adb22357523109f957b49e6cdda8b698", - "size": 122522 + "path": "en/api/terraform/messages/batches/delete.md", + "sha256": "3e4726d1df3ce814f8ccb4692e4fa1ac904f1594692044e2b0f5cc0e73471b8d", + "size": 89250 }, { - "url": "https://platform.claude.com/docs/en/api/java/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches/results", "status": "success", - "path": "en/api/java/messages/count_tokens.md", - "sha256": "68be31a803aeae8d38432220628051f2e65a94c8d0acc9dbf1ccfce04b9053cd", - "size": 96644 + "path": "en/api/terraform/messages/batches/results.md", + "sha256": "5cbac210906557e2acb7c2edf9d9a8ef1f80395db66f131ec51f4fefb56b8005", + "size": 89253 }, { - "url": "https://platform.claude.com/docs/en/api/java/messages/batches", + "url": "https://platform.claude.com/docs/en/api/terraform/models", "status": "success", - "path": "en/api/java/messages/batches.md", - "sha256": "8fec18621022ffb1cbab40f0f10c0f0ba47bc155fa1d04d462b84ab8b89b26f9", - "size": 248314 + "path": "en/api/terraform/models.md", + "sha256": "3cfc6b65e285c2f2ff6286b041a25e73cb275b7f250caa3ab3f0ecefa2226e0b", + "size": 89191 }, { - "url": "https://platform.claude.com/docs/en/api/java/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/terraform/models/list", "status": "success", - "path": "en/api/java/messages/batches/create.md", - "sha256": "ce5d431a1bfc2b02bd617b110554e29d414eaffa91725f9338788a3f97e69e36", - "size": 116529 + "path": "en/api/terraform/models/list.md", + "sha256": "ebdb9e8ccf1c617c630198354826daca517be53a81badf95fffccf185f6d302f", + "size": 89210 }, { - "url": "https://platform.claude.com/docs/en/api/java/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/terraform/models/retrieve", "status": "success", - "path": "en/api/java/messages/batches/retrieve.md", - "sha256": "31ef3a6186ee81e8555c194abe39c78c319e393924dbe81bfe547c07af936232", - "size": 4046 + "path": "en/api/terraform/models/retrieve.md", + "sha256": "27451f5b95c2fc6bfffaac7090dd753618633ce72a160459e013f6973f0ae0a7", + "size": 89222 }, { - "url": "https://platform.claude.com/docs/en/api/java/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/terraform/beta", "status": "success", - "path": "en/api/java/messages/batches/list.md", - "sha256": "4c72371fbbc0ea3a4862f11ad8557966466adb6dd7385e02e0f6740e0bae0e0e", - "size": 4266 + "path": "en/api/terraform/beta.md", + "sha256": "83e0bbb35809f2524bd40224b51cb64eaffb1f3e5156ad9e728f59f3a2086dc1", + "size": 89185 }, { - "url": "https://platform.claude.com/docs/en/api/java/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/models", "status": "success", - "path": "en/api/java/messages/batches/cancel.md", - "sha256": "1839e1ce519275e06452a811f7eb16628dba51fee26deb770677aa8894b7a5b3", - "size": 4350 + "path": "en/api/terraform/beta/models.md", + "sha256": "39a81b36524f3703a07f2fa6476904710996676a821c33d6b08ef2dfb96a71d6", + "size": 89210 + }, + { + "url": "https://platform.claude.com/docs/en/api/terraform/beta/models/list", + "status": "success", + "path": "en/api/terraform/beta/models/list.md", + "sha256": "cca9b3cc905c718c578a4566510c54308f6e3256c1b1be9970891feef6e258b2", + "size": 89229 + }, + { + "url": "https://platform.claude.com/docs/en/api/terraform/beta/models/retrieve", + "status": "success", + "path": "en/api/terraform/beta/models/retrieve.md", + "sha256": "553e77510efb17c977836535050ac49ad60e20c3ecc51d8143422a8676581235", + "size": 89241 + }, + { + "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages", + "status": "success", + "path": "en/api/terraform/beta/messages.md", + "sha256": "96613b25a7833a9648786f44080de9a3a65da66ad188bc55323826f6bec05df5", + "size": 89216 + }, + { + "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/create", + "status": "success", + "path": "en/api/terraform/beta/messages/create.md", + "sha256": "24c5af670c18fd9ba11febd0a0cc6fd51bb79fae7aa72b3f891d164b96d178c1", + "size": 89241 + }, + { + "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/count_tokens", + "status": "success", + "path": "en/api/terraform/beta/messages/count_tokens.md", + "sha256": "67ebabb8d80ed30854ad25bd33374165a413937912048f712c0d250ad958040b", + "size": 89259 + }, + { + "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches", + "status": "success", + "path": "en/api/terraform/beta/messages/batches.md", + "sha256": "ab24767934fb3467410bd54f045d4e765bc7a070f2cb0903c4e95cf59c256f22", + "size": 89244 }, { - "url": "https://platform.claude.com/docs/en/api/java/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches/create", "status": "success", - "path": "en/api/java/messages/batches/delete.md", - "sha256": "e0b8f507d75c528ba15e08056989139d14e0f70172ce518ec9105b5a2cfbb48d", - "size": 1498 + "path": "en/api/terraform/beta/messages/batches/create.md", + "sha256": "de774466c2d1dd0f37f4549f8e4b75255f9e746372d5cc80b8aae574adee0ca9", + "size": 89269 }, { - "url": "https://platform.claude.com/docs/en/api/java/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches/retrieve", "status": "success", - "path": "en/api/java/messages/batches/results.md", - "sha256": "2b7d45a99474a2e7ec57ab7ab3bb27e58575a0017b53834353b71d4fa3274030", - "size": 30472 + "path": "en/api/terraform/beta/messages/batches/retrieve.md", + "sha256": "69c309ec1aa7bc99b9a012d6c5921c96999956bf91e3f3d8fa69ca6dc07b242c", + "size": 89275 }, { - "url": "https://platform.claude.com/docs/en/api/java/models", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches/list", "status": "success", - "path": "en/api/java/models.md", - "sha256": "fbeaf7ac96e5a6e39d87659c132e8953288d149b2a167ab1127cb4e1fc39100e", - "size": 24482 + "path": "en/api/terraform/beta/messages/batches/list.md", + "sha256": "5ee56a22af246dbdcb91bb3540a1231f75359fe726706ad373b283378a1e4fb8", + "size": 89263 }, { - "url": "https://platform.claude.com/docs/en/api/java/models/list", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches/cancel", "status": "success", - "path": "en/api/java/models/list.md", - "sha256": "50cdfdf1b1a5eb9577a77cffa7644aca1fccf2bbb72e0d52a0e5bbb5cc442570", - "size": 7087 + "path": "en/api/terraform/beta/messages/batches/cancel.md", + "sha256": "1ba04faef236328441c19a51f81338591aba05f6f34b4fb72c4277186f0378cf", + "size": 89269 }, { - "url": "https://platform.claude.com/docs/en/api/java/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches/delete", "status": "success", - "path": "en/api/java/models/retrieve.md", - "sha256": "e783d88a291934cd7c2421abf17b0adb8b0a3fd41d0acff11aef4564e1f24826", - "size": 6725 + "path": "en/api/terraform/beta/messages/batches/delete.md", + "sha256": "3f56308ce376a1c3a86131793751d847b147069b988aa4ba19c7217052af5a38", + "size": 89269 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches/results", "status": "success", - "path": "en/api/java/beta.md", - "sha256": "0d2c16b59c9e1f321b93462d9548bad8061b2bc9845c68f3f70bf2a28f6994b6", - "size": 1207081 + "path": "en/api/terraform/beta/messages/batches/results.md", + "sha256": "666ab928f8e8f4b4753fd6de4763df14dbe29de3d1d7ce97c821ce686f8d15e1", + "size": 89272 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/models", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/agents", "status": "success", - "path": "en/api/java/beta/models.md", - "sha256": "e6795265860633374e0516d76819656472ae5f1adbbb9f578d04ab386ba23775", - "size": 24981 + "path": "en/api/terraform/beta/agents.md", + "sha256": "aa0b7c019d462a3e06d9b174980a0be11577dfb24e75b356c1dee84e75561c64", + "size": 89210 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/models/list", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/agents/create", "status": "success", - "path": "en/api/java/beta/models/list.md", - "sha256": "cab2d4602dcab3b625f8bb55220d6bb66e46fa41643a834d06d644782d8697e8", - "size": 7195 + "path": "en/api/terraform/beta/agents/create.md", + "sha256": "bc691d472c8300a041c37b42b82bca7fb92c3ca1567552dbe044927505ec60da", + "size": 89235 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/agents/list", "status": "success", - "path": "en/api/java/beta/models/retrieve.md", - "sha256": "0d076cd83d56fc0a88e10796c58a3243a80fed93a3b39aa74c42ab242978a1c2", - "size": 6849 + "path": "en/api/terraform/beta/agents/list.md", + "sha256": "34b3c42864c89c05d16e097d7c4745daac91fa52f4dcf109c3883f2bf08bdd17", + "size": 89229 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/messages", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/agents/retrieve", "status": "success", - "path": "en/api/java/beta/messages.md", - "sha256": "2161e74f6399f81669a499549d87ff240587fcb732814136ada4e942701a234e", - "size": 1119999 + "path": "en/api/terraform/beta/agents/retrieve.md", + "sha256": "a15b083b37127b6e3ed53bb246a44730b5540901012feead25f97786b1738817", + "size": 89241 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/messages/create", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/agents/update", "status": "success", - "path": "en/api/java/beta/messages/create.md", - "sha256": "9f6c66f81e399757404ddfd6a055992ffbe5a1caa741fadc01d67c1aa7ee4a43", - "size": 151133 + "path": "en/api/terraform/beta/agents/update.md", + "sha256": "bc0f2c5cedd90ef7b3e69ea9b47ff2ec75737541552d5e0cca5f09a9bff3d3ea", + "size": 89235 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/agents/archive", "status": "success", - "path": "en/api/java/beta/messages/count_tokens.md", - "sha256": "f044d2ecd009cc1a996bc1bf60a77e3bee52254aaac7e021ee8bd6dcf36a986d", - "size": 116815 + "path": "en/api/terraform/beta/agents/archive.md", + "sha256": "cc7362ee0352fc0fcbd4d5c69889617332a7b47a2460e08e3db57e449a1dcae8", + "size": 89238 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/agents/versions", "status": "success", - "path": "en/api/java/beta/messages/batches.md", - "sha256": "aeac9b26458820441ecfcb37ac53c84dce651c09fbe95d18199b6c23c0f4e071", - "size": 316406 + "path": "en/api/terraform/beta/agents/versions.md", + "sha256": "5d0d3c226a046381b9187b18333f9924d94213fddf97b0144080925d7723e555", + "size": 89241 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/agents/versions/list", "status": "success", - "path": "en/api/java/beta/messages/batches/create.md", - "sha256": "cf7e1791a139105925b08b16044b4c89644d08fcb3677d13f655bff01a11141f", - "size": 142162 + "path": "en/api/terraform/beta/agents/versions/list.md", + "sha256": "abca45a51f9b7c4467abc69a38968fd8281b1ea263f217edc78a2aa1e6607a0a", + "size": 89260 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/environments", "status": "success", - "path": "en/api/java/beta/messages/batches/retrieve.md", - "sha256": "c265b929ed6a0d6ad00de81812d02d5d8e7c2b6473352a6c110b9bc9a5b07d71", - "size": 5592 + "path": "en/api/terraform/beta/environments.md", + "sha256": "56a7b6216610b066772c1339f125e8e92c629fa0a5dcab60fd9ab61d1f62432c", + "size": 89228 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/environments/create", "status": "success", - "path": "en/api/java/beta/messages/batches/list.md", - "sha256": "6c70571ebb5051939a1301640bf63f352337165c7b8b0e7677922cd59b854602", - "size": 5796 + "path": "en/api/terraform/beta/environments/create.md", + "sha256": "f08bcf8cb38e75e4257115e78be3e2d34b71e27ea03899f548fd142eb930648c", + "size": 89253 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/environments/list", "status": "success", - "path": "en/api/java/beta/messages/batches/cancel.md", - "sha256": "de25b9555672c29c6e1d883d7f6a819344da0e48db5b3a52fd05ab31869b2f8c", - "size": 5896 + "path": "en/api/terraform/beta/environments/list.md", + "sha256": "ae94b937499b32cf214322f8dfee9b18be78cdcf4c37106bd828487f47d7d9dc", + "size": 89247 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/environments/retrieve", "status": "success", - "path": "en/api/java/beta/messages/batches/delete.md", - "sha256": "2edfbf0efa5528511a256a52dde839cc3fddf05ab6988bdc1c3975eb9d09a77d", - "size": 3040 + "path": "en/api/terraform/beta/environments/retrieve.md", + "sha256": "8e7469b8870d2c9ffa1513dd0fc6042531516c030e14bf858ed7e47652a9da23", + "size": 89259 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/environments/update", "status": "success", - "path": "en/api/java/beta/messages/batches/results.md", - "sha256": "9222cd0fb25a91bdad32c60be3eef5dc93920b4112bf8d4c832c935108e79619", - "size": 40921 + "path": "en/api/terraform/beta/environments/update.md", + "sha256": "9eee653f82e2cf513a794d2ea402fe17396f5d28d27e5640e650d03ab61ba4a8", + "size": 89253 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/files", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/environments/delete", "status": "success", - "path": "en/api/java/beta/files.md", - "sha256": "a360e5431c518dd98b4a5604d9a52e64b1404566f199fed42ba120d4878fdb91", - "size": 15089 + "path": "en/api/terraform/beta/environments/delete.md", + "sha256": "2c136e997f964176cf43423cd22ef2a4d38433a5ca6479a0692e2d80e185066b", + "size": 89253 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/files/upload", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/environments/archive", "status": "success", - "path": "en/api/java/beta/files/upload.md", - "sha256": "60d0f8ff35b8541035fe43f300fab84e3e6b5653858113023136e828e7d6b197", - "size": 3067 + "path": "en/api/terraform/beta/environments/archive.md", + "sha256": "604344462361964be54bba742c3aa9d2a76b10e739494d416d6ee979c03f6f69", + "size": 89256 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/files/list", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions", "status": "success", - "path": "en/api/java/beta/files/list.md", - "sha256": "1db339de8db95d6b5517f69ffc0d84deca7afe78e93c3c52ba67db7308081dd0", - "size": 3276 + "path": "en/api/terraform/beta/sessions.md", + "sha256": "86d6d76f2aeff5d9533b497fa20114d346dd8fe9baedb1bbb43d3b4bf8fd540d", + "size": 89216 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/files/download", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/create", "status": "success", - "path": "en/api/java/beta/files/download.md", - "sha256": "74472ae26d5130936ef6c73cb9445ed611059a6ac1d06b780ba3bd4e9a4de7d7", - "size": 2321 + "path": "en/api/terraform/beta/sessions/create.md", + "sha256": "5791b28788bff03a0b85fcded77e883f6483fc65ca067c48fd2ea2d00e33f733", + "size": 89241 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/files/retrieve_metadata", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/list", "status": "success", - "path": "en/api/java/beta/files/retrieve_metadata.md", - "sha256": "bea2c6095eb02dcb0f66c176e6a2b18249f06e2030d65251360c8130176a35a0", - "size": 3000 + "path": "en/api/terraform/beta/sessions/list.md", + "sha256": "fc9e711ef6b95e3c7f82d0edaff67f8a99537eb1acf079e4cbfd580d9b1a6674", + "size": 89235 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/files/delete", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/retrieve", "status": "success", - "path": "en/api/java/beta/files/delete.md", - "sha256": "92dfca5a9c737757ab31de30f94f3275afc36655b9d91601d65be47a5fdcc063", - "size": 2539 + "path": "en/api/terraform/beta/sessions/retrieve.md", + "sha256": "c1f76f4487c830a4a4543467a28b135208c56cd1f0ef119f4bb588299d6b7ac5", + "size": 89247 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/skills", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/update", "status": "success", - "path": "en/api/java/beta/skills.md", - "sha256": "c712267b317f71f0489f905a9436dbce9e1d1a629164a6c97b09eb27dcac799c", - "size": 27466 + "path": "en/api/terraform/beta/sessions/update.md", + "sha256": "d0c6c3b788524ace9e508976b28cd52fb19b37413aca7930eaef113ebebffb58", + "size": 89241 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/skills/create", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/delete", "status": "success", - "path": "en/api/java/beta/skills/create.md", - "sha256": "53326ceebeaba8a3c6f09dad26acd3ea2666788e14ce2122d57bbe68f1e618da", - "size": 3544 + "path": "en/api/terraform/beta/sessions/delete.md", + "sha256": "a9adf922f93edec9794a3ae8e27a6897d43758a03f0cc8c4e8cbab126d2b3ef2", + "size": 89241 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/skills/list", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/archive", "status": "success", - "path": "en/api/java/beta/skills/list.md", - "sha256": "f3bfbbe9e5f625ab29a45d1f715f2978865a32c72c3f02fc9a518280968ea738", - "size": 3703 + "path": "en/api/terraform/beta/sessions/archive.md", + "sha256": "f09f6ef44a317737d867af9a597d0ccc51febb9749822fc0484672f7b64870dc", + "size": 89244 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/skills/retrieve", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/events", "status": "success", - "path": "en/api/java/beta/skills/retrieve.md", - "sha256": "484f3e112c5b0e7d27328dc8b5f1178bd352cc10163606fc5f19c31b55234d46", - "size": 3357 + "path": "en/api/terraform/beta/sessions/events.md", + "sha256": "3fa1763e9be866f14d9cd4d36448d95adbb10fa7d193f395203bad3dcc60bb45", + "size": 89241 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/skills/delete", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/events/list", "status": "success", - "path": "en/api/java/beta/skills/delete.md", - "sha256": "3a6e8a84c857209f40866a9936a13c5f0d96d58f19e1498c5e52122032b1d604", - "size": 2664 + "path": "en/api/terraform/beta/sessions/events/list.md", + "sha256": "242d9f8999cb0c89791849759d652c4106cf3ce6c31290f3a85019d03eeee995", + "size": 89260 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/skills/versions", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/events/send", "status": "success", - "path": "en/api/java/beta/skills/versions.md", - "sha256": "0bbe5cd2714ca58cd003416ba35f1986ad56671c35a055a38ce02fd2dd5e02d3", - "size": 14184 + "path": "en/api/terraform/beta/sessions/events/send.md", + "sha256": "e44dce923bd6f570592dd712412bc98de6b5af041c291ad99614d42e08c7729b", + "size": 89260 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/skills/versions/create", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/events/stream", "status": "success", - "path": "en/api/java/beta/skills/versions/create.md", - "sha256": "7c218ca01f1e191947806c711c7495117ee640b4f070c67810c650e4235940cc", - "size": 3669 + "path": "en/api/terraform/beta/sessions/events/stream.md", + "sha256": "4dad62605d4395dc67f35cde335062327df5629f0e45ea04f8304ff5e4587585", + "size": 89266 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/skills/versions/list", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/resources", "status": "success", - "path": "en/api/java/beta/skills/versions/list.md", - "sha256": "62b78395c4b77606a57b6ace75a45ae399abfbb5a678adcd29f5212b9ab11ee5", - "size": 3660 + "path": "en/api/terraform/beta/sessions/resources.md", + "sha256": "7b6db11c66b268777730d0ec18162fc488917e4d195a0f05c4997a8da91f27a9", + "size": 89250 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/skills/versions/retrieve", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/resources/add", "status": "success", - "path": "en/api/java/beta/skills/versions/retrieve.md", - "sha256": "76a25bf9bcfcdd406891b0b960c59779987c5771aff8727fe25f3d56cc0e0759", - "size": 3776 + "path": "en/api/terraform/beta/sessions/resources/add.md", + "sha256": "a0c3dc482882d17255e71b4538bba8f3ca8cb61abced7613e8608da97df5986f", + "size": 89266 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/skills/versions/delete", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/resources/list", "status": "success", - "path": "en/api/java/beta/skills/versions/delete.md", - "sha256": "107e78e5d518b798f145cf990574d3bfb89587b07e3c99d6a98afa94cdc15a43", - "size": 3064 + "path": "en/api/terraform/beta/sessions/resources/list.md", + "sha256": "d99a2ae7c9f17eb5f9f1edb65b36062fbcdd5012c8c1b86dcb348f6f5b4bfd4f", + "size": 89269 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/user_profiles", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/resources/retrieve", "status": "success", - "path": "en/api/java/beta/user_profiles.md", - "sha256": "047bbee9504f26847da9da62280fe7777ca7233eea56d0d7f7cd21ae05f60c34", - "size": 14790 + "path": "en/api/terraform/beta/sessions/resources/retrieve.md", + "sha256": "914d66347917633e4added512f8e661c2bf020bd9da122d18c7067d22bee1a02", + "size": 89281 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/user_profiles/create", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/resources/update", "status": "success", - "path": "en/api/java/beta/user_profiles/create.md", - "sha256": "73b6c3f3f91b7294fbf9b47b0994e7df719aec670a00931a174a5887030eec78", - "size": 2894 + "path": "en/api/terraform/beta/sessions/resources/update.md", + "sha256": "52ee6d2d08319712b12bcce0bcf50cdbfee336e5775465b4605976094b161f05", + "size": 89275 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/user_profiles/list", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/sessions/resources/delete", "status": "success", - "path": "en/api/java/beta/user_profiles/list.md", - "sha256": "5f84fb66814fd8056515b57800b7f2e6595641100ee083869b1ad89b5917ea14", - "size": 2853 + "path": "en/api/terraform/beta/sessions/resources/delete.md", + "sha256": "d49ac6fb6d8305ab40ee06131e97b001ee2c51fdcee85792acdfe03844d8330a", + "size": 89275 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/user_profiles/retrieve", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults", "status": "success", - "path": "en/api/java/beta/user_profiles/retrieve.md", - "sha256": "825bda62fce2272ab0f8a812cdd2207883783802ad7293987566d69667a10402", - "size": 2694 + "path": "en/api/terraform/beta/vaults.md", + "sha256": "669fb85352cc13879e731bae81b3a34822c671144aeacef2109f1c854188825a", + "size": 89210 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/user_profiles/update", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/create", "status": "success", - "path": "en/api/java/beta/user_profiles/update.md", - "sha256": "4b99c3c6145279edc006185a3a38a3d5b269d62b658f73cf17062a1faad2baa5", - "size": 3020 + "path": "en/api/terraform/beta/vaults/create.md", + "sha256": "8f0c22839e808e441d63faf801fc9755dc5c886f3e1efb52729dfe351986fbb4", + "size": 89235 }, { - "url": "https://platform.claude.com/docs/en/api/java/beta/user_profiles/create_enrollment_url", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/list", "status": "success", - "path": "en/api/java/beta/user_profiles/create_enrollment_url.md", - "sha256": "cbb373297c7ec30601fd81587524219d251c467f8e643065d569aded9e7b637c", - "size": 2679 + "path": "en/api/terraform/beta/vaults/list.md", + "sha256": "d424cc64ce675da7374523f05acf65db0c8ba5fa8f64a53cb38c9e718981f0d0", + "size": 89229 }, { - "url": "https://platform.claude.com/docs/en/api/go/completions", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/retrieve", "status": "success", - "path": "en/api/go/completions.md", - "sha256": "59503fde3d089d8c31a585ec37e7d9a968bb086b8c5d79bf1b6167bfbae2e2e6", - "size": 12155 + "path": "en/api/terraform/beta/vaults/retrieve.md", + "sha256": "614f42e3774ec87fb6e638d05f6f29b7e4e7dde8d4efb968bba06a2c9116dcf0", + "size": 89241 }, { - "url": "https://platform.claude.com/docs/en/api/go/completions/create", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/update", "status": "success", - "path": "en/api/go/completions/create.md", - "sha256": "98366cf044bf37a7106a634d608eea40268e6a76690db9a167bb9ea8dca4c744", - "size": 9091 + "path": "en/api/terraform/beta/vaults/update.md", + "sha256": "4673e1efffd6fa54de0d75c7d5ebb80809b41bd3bb413e1dafee15fc2ba666a5", + "size": 89235 }, { - "url": "https://platform.claude.com/docs/en/api/go/messages", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/delete", "status": "success", - "path": "en/api/go/messages.md", - "sha256": "6d1291b8603e7b94434e0e780d5713b94dd2aecf1adaeaba04526127bb0ad064", - "size": 1096821 + "path": "en/api/terraform/beta/vaults/delete.md", + "sha256": "dc2194630d01df56028a80d0b5d4be61a79df79d45af466d8a964ea2c147168b", + "size": 89235 }, { - "url": "https://platform.claude.com/docs/en/api/go/messages/create", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/archive", "status": "success", - "path": "en/api/go/messages/create.md", - "sha256": "5fb6c4c9c3fc29ab14ff97f9283eca5d305c8dc2a8758913d92f2a1fa8851853", - "size": 144211 + "path": "en/api/terraform/beta/vaults/archive.md", + "sha256": "7077426e15d28975066d224ee9032cf5fff7186b6c769f5e3f70b83bd07e0947", + "size": 89238 }, { - "url": "https://platform.claude.com/docs/en/api/go/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/credentials", "status": "success", - "path": "en/api/go/messages/count_tokens.md", - "sha256": "4b76269bb382fbcd104dbf6b790322d2a57e5613a3366abd74928354fbcbf166", - "size": 112866 + "path": "en/api/terraform/beta/vaults/credentials.md", + "sha256": "af3ef420b53dc6060eadbe9c1d6665a1259aa766f2ebef1ba412848d58a4e7d4", + "size": 89250 }, { - "url": "https://platform.claude.com/docs/en/api/go/messages/batches", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/credentials/create", "status": "success", - "path": "en/api/go/messages/batches.md", - "sha256": "5c8b47fd2e2822f217b6354f095171a6f8282579241227758b94c081df16b976", - "size": 287749 + "path": "en/api/terraform/beta/vaults/credentials/create.md", + "sha256": "3fbb345d62b338985e2c555e862cd959e50596c7f0ef3c31a73773061246c450", + "size": 89275 }, { - "url": "https://platform.claude.com/docs/en/api/go/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/credentials/list", "status": "success", - "path": "en/api/go/messages/batches/create.md", - "sha256": "153e429cc0b36233463a249933b61a33fe1a89e705c5c38c34aba0851fe7fa50", - "size": 133943 + "path": "en/api/terraform/beta/vaults/credentials/list.md", + "sha256": "0021fe29f39544b0c0be94a9baaeb20fb93db4012de3f1caa0ce92dc2ccc0835", + "size": 89269 }, { - "url": "https://platform.claude.com/docs/en/api/go/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/credentials/retrieve", "status": "success", - "path": "en/api/go/messages/batches/retrieve.md", - "sha256": "bdc366efbc71476c7dc058e4d19442d5db0216f412475fee3101f3ed5884a943", - "size": 3946 + "path": "en/api/terraform/beta/vaults/credentials/retrieve.md", + "sha256": "d08ab0411a6aae5af8828c2a0407a5dccec296e57c90f0768117f595ff3062b8", + "size": 89281 }, { - "url": "https://platform.claude.com/docs/en/api/go/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/credentials/update", "status": "success", - "path": "en/api/go/messages/batches/list.md", - "sha256": "13803b84761d4e03026bfa836b268d1f58ebf2708efa4815f72c762dd11cb110", - "size": 4271 + "path": "en/api/terraform/beta/vaults/credentials/update.md", + "sha256": "170e1b5210fb633b45cf8383b910359697ca4e54bb8ad2bd4d888768eb478773", + "size": 89275 }, { - "url": "https://platform.claude.com/docs/en/api/go/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/credentials/delete", "status": "success", - "path": "en/api/go/messages/batches/cancel.md", - "sha256": "6a096b0fc9b9b960628e7930aa2196cb7b7145e55a77b008a554f0c28afc1358", - "size": 4268 + "path": "en/api/terraform/beta/vaults/credentials/delete.md", + "sha256": "47086357ac9d78790689741b5e2dc394ae8f0dd58d12866fda67ff233c614ca9", + "size": 89275 }, { - "url": "https://platform.claude.com/docs/en/api/go/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/vaults/credentials/archive", "status": "success", - "path": "en/api/go/messages/batches/delete.md", - "sha256": "646f74b47911415e5bf68f98faf63b3195123369f63ff9ea9d47029de680a535", - "size": 1298 + "path": "en/api/terraform/beta/vaults/credentials/archive.md", + "sha256": "8127d2ddedcbf338bc8cc13f7a9041b3dbde2faf9deb0459e3ebf0c1d95bd612", + "size": 89278 }, { - "url": "https://platform.claude.com/docs/en/api/go/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/files", "status": "success", - "path": "en/api/go/messages/batches/results.md", - "sha256": "b5bac6e09cb6a028f9b7589d991bfee2b8c1f1e305c06f0972d05797bfd1f4fb", - "size": 35809 + "path": "en/api/terraform/beta/files.md", + "sha256": "4efcd4b4e4be87fc69601edcbb707e4e0f4b7b01a6800165efde277c2f73d4a4", + "size": 89207 }, { - "url": "https://platform.claude.com/docs/en/api/go/models", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/files/upload", "status": "success", - "path": "en/api/go/models.md", - "sha256": "8429d69a3e857638d74963033564d3104fa3ec06f3754301c7bb323c7e11ad1e", - "size": 25418 + "path": "en/api/terraform/beta/files/upload.md", + "sha256": "4a0a77d8eac2372dcc332ed3e1d753c640fc21b04585c050df6ef3fd9a2f9a56", + "size": 89232 }, { - "url": "https://platform.claude.com/docs/en/api/go/models/list", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/files/list", "status": "success", - "path": "en/api/go/models/list.md", - "sha256": "0571cba13a2b7b09a3333076375a0e9a94f4f6f97621a9f7753ae6ddc8fe6fb8", - "size": 7693 + "path": "en/api/terraform/beta/files/list.md", + "sha256": "5c15bd659e2a0755b063daf0a47040121c3bfb9bbbbe0fc970d7f0f99b594cca", + "size": 89226 }, { - "url": "https://platform.claude.com/docs/en/api/go/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/files/download", "status": "success", - "path": "en/api/go/models/retrieve.md", - "sha256": "4fae89ea093a5ac46adb98381f662d0010731ea837272548b219296d57795a5b", - "size": 7268 + "path": "en/api/terraform/beta/files/download.md", + "sha256": "b5f3bbf4be4f399b393cbb6ffb205261b304bad365a2c653a1a94832f31b0bc6", + "size": 89238 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/files/retrieve_metadata", "status": "success", - "path": "en/api/go/beta.md", - "sha256": "295bc3032061a29ede1a9a790c82fbce4c0448500d1efe5002b5a238da629dac", - "size": 1446713 + "path": "en/api/terraform/beta/files/retrieve_metadata.md", + "sha256": "9b90c2fc6896d7a34bc8f4e61d571f8c847886826fa69bc71d194aa44e68dfd7", + "size": 89265 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/models", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/files/delete", "status": "success", - "path": "en/api/go/beta/models.md", - "sha256": "a31b5605ca82acc356637db766f8e57504f780ceb94317b6bb2d701234067429", - "size": 25905 + "path": "en/api/terraform/beta/files/delete.md", + "sha256": "4a4e786d5c76c7e8b25808e5cee604530b67132b73580b9cbb28c8eec628e725", + "size": 89232 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/models/list", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills", "status": "success", - "path": "en/api/go/beta/models/list.md", - "sha256": "c35ceecb048ec8cc89a97329245d2e0b62725266aaa31093d21d2e5bb92e216d", - "size": 7799 + "path": "en/api/terraform/beta/skills.md", + "sha256": "1a6b6a9c7d835d8d09356ac64fcfda3fdc776f389d5ec8e9c2ffae040f53d6a0", + "size": 89210 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/create", "status": "success", - "path": "en/api/go/beta/models/retrieve.md", - "sha256": "38de992f281de9b94b74e3c695e25e8697d1bfa40a0dbdfd557d11d0195673c0", - "size": 7382 + "path": "en/api/terraform/beta/skills/create.md", + "sha256": "050fc00ab02744194100cac7b96ed3f6dfab26e9089981e94709299a765e89b9", + "size": 89235 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/messages", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/list", "status": "success", - "path": "en/api/go/beta/messages.md", - "sha256": "ab2aa648632ebcb7024104766475165a2dc329d332876f73c0dbf9500f17419b", - "size": 1343750 + "path": "en/api/terraform/beta/skills/list.md", + "sha256": "2784a411e457a6046afd4b2ee9657314082b8e83252974bea013137a531a10b6", + "size": 89229 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/messages/create", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/retrieve", "status": "success", - "path": "en/api/go/beta/messages/create.md", - "sha256": "17e11f7a7332ccc7b0b65868c169bea1a522a1901a35aced7a6d7eeb732f9f6d", - "size": 180326 + "path": "en/api/terraform/beta/skills/retrieve.md", + "sha256": "4d8696b61e0bd7ff70de9a2275327604f07e412a8bd063e9ebb093a420118478", + "size": 89241 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/delete", "status": "success", - "path": "en/api/go/beta/messages/count_tokens.md", - "sha256": "ce94bbc4f02380f7272ba21a278bcfb2ba911d4788e2f561974c2bb72263e3f2", - "size": 139177 + "path": "en/api/terraform/beta/skills/delete.md", + "sha256": "7ddeddda21ce2d019005b4734ee7d9e87df08f782e4873d393d09aeddcb26126", + "size": 89235 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/versions", "status": "success", - "path": "en/api/go/beta/messages/batches.md", - "sha256": "038b0cbf3157bf93aa192fde1d89a608705bf5588c02985e1f2f295022ab3104", - "size": 371465 + "path": "en/api/terraform/beta/skills/versions.md", + "sha256": "0c7a8918fd218801bc2af029ee11bce2acb865f85e4f04627551f4fe412c7740", + "size": 89241 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/versions/create", "status": "success", - "path": "en/api/go/beta/messages/batches/create.md", - "sha256": "b76ff8f6927fb70fd0404eb026f52075ca5c3861b7700ca4fd7bd54a274e1b17", - "size": 166004 + "path": "en/api/terraform/beta/skills/versions/create.md", + "sha256": "a76c4bd3750ca37a7c332ce671bc9a98cbc26bf784817aa35cc3da4fc4d3ce37", + "size": 89266 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/versions/list", "status": "success", - "path": "en/api/go/beta/messages/batches/retrieve.md", - "sha256": "70a3f4f19f8373adbc15ff880511cf4f655ea7854f3b5b04b220f46685e7d790", - "size": 6403 + "path": "en/api/terraform/beta/skills/versions/list.md", + "sha256": "b3514dc1bfdc61f9c21fd8d413fbd9a73e327ccf56943c57250d35082d6af204", + "size": 89260 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/versions/retrieve", "status": "success", - "path": "en/api/go/beta/messages/batches/list.md", - "sha256": "685b56ad69475cbd5c0df3730cee15bc6f19a2be8a9b835934846e32eae147f1", - "size": 6677 + "path": "en/api/terraform/beta/skills/versions/retrieve.md", + "sha256": "f5a32bc1c3ccb533c8b261539bc08ec1cd2d974e73d2edf8356d781e1c96f83e", + "size": 89272 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/versions/delete", "status": "success", - "path": "en/api/go/beta/messages/batches/cancel.md", - "sha256": "c06f7f3a8b2467c5d0304322c4b0449a3af95886c68688a91fb56b085fe8d06c", - "size": 6729 + "path": "en/api/terraform/beta/skills/versions/delete.md", + "sha256": "1eba292659571166a873b4eb9b8eb9033d4de55d39102fee318197652c967203", + "size": 89266 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/cli/completions", "status": "success", - "path": "en/api/go/beta/messages/batches/delete.md", - "sha256": "d9876fd6c2f63fc91fc61f6731f56b84b425be29e5142f2d794071b35f5d9151", - "size": 3727 + "path": "en/api/cli/completions.md", + "sha256": "f9524831e9dd58858e90095eea2ef692bab2eb6d3df50748d1a2f2687830179d", + "size": 8201 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/cli/completions/create", "status": "success", - "path": "en/api/go/beta/messages/batches/results.md", - "sha256": "7af2d1e8802469198d061892b91f112997b15f9c235b08e60cf33d3c38b714a5", - "size": 48315 + "path": "en/api/cli/completions/create.md", + "sha256": "bc91dabfe458359566d83e2621b90265d492cdd5b5158d695f6ab01c849a7cb9", + "size": 5802 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/files", + "url": "https://platform.claude.com/docs/en/api/cli/messages", "status": "success", - "path": "en/api/go/beta/files.md", - "sha256": "77034cf1b8975999fcc63ba8c80dc48f64404f77cba17e2d78b1a2cbef48895a", - "size": 18493 + "path": "en/api/cli/messages.md", + "sha256": "31c7ed25987f97db1f27534987a9cc11d943311b3fe2bf8f34e1c8019768ddfa", + "size": 557697 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/files/upload", + "url": "https://platform.claude.com/docs/en/api/cli/messages/create", "status": "success", - "path": "en/api/go/beta/files/upload.md", - "sha256": "85b1f5eff0d948b4af355c743d779862c129095bf31b72dddb104dfa383ba92f", - "size": 3659 + "path": "en/api/cli/messages/create.md", + "sha256": "2fa5d01cade2dc0d88486b8efcbc7422f7b73a625c641eaef4f4c5689cc2538a", + "size": 30178 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/files/list", + "url": "https://platform.claude.com/docs/en/api/cli/messages/count_tokens", "status": "success", - "path": "en/api/go/beta/files/list.md", - "sha256": "7bdca38f109e5f5dfe67565b45cdea5347699282b3f0eadca6dab99dd5f08f75", - "size": 3984 + "path": "en/api/cli/messages/count_tokens.md", + "sha256": "3d5b6299d305ceda639355f47a43204ff19c4e1a4a0e387e57882cb267da56e5", + "size": 6983 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/files/download", + "url": "https://platform.claude.com/docs/en/api/cli/messages/batches", "status": "success", - "path": "en/api/go/beta/files/download.md", - "sha256": "9c042b40a520c63240db41f6efbb35b396075ed75e7a013a1d1b25e86b22e33b", - "size": 3052 + "path": "en/api/cli/messages/batches.md", + "sha256": "8fadacea02f6cd713fa10cf69d76b05c163d57783ef3dfb21cd75758f8dad855", + "size": 119148 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/files/retrieve_metadata", + "url": "https://platform.claude.com/docs/en/api/cli/messages/batches/create", "status": "success", - "path": "en/api/go/beta/files/retrieve_metadata.md", - "sha256": "be297dfa313b64c74bd1c1669c08222cc22aa5169634b9552bedfcf5d01051e8", - "size": 3619 + "path": "en/api/cli/messages/batches/create.md", + "sha256": "8944e8b5443ce4fd3f852ef7f895deeaa820c723482e773902bf17454a1aae72", + "size": 3667 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/files/delete", + "url": "https://platform.claude.com/docs/en/api/cli/messages/batches/retrieve", "status": "success", - "path": "en/api/go/beta/files/delete.md", - "sha256": "9371ef05d6e7ed1471e9be3a6acb9d132f0f2232a42825916751432b80821a46", - "size": 3261 + "path": "en/api/cli/messages/batches/retrieve.md", + "sha256": "0cba952f88c24c0659e6ae42d778aedd48eb676081ed59eae8fdaea5f59178d8", + "size": 3427 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/skills", + "url": "https://platform.claude.com/docs/en/api/cli/messages/batches/list", "status": "success", - "path": "en/api/go/beta/skills.md", - "sha256": "caff12e86fc2bf24527eade364b0613a2f9e95d4f83b6d8cffa921bd355e3540", - "size": 32693 + "path": "en/api/cli/messages/batches/list.md", + "sha256": "f900790450bfc351e437900c71f86ad3cd4f4dcba2a3f0162391e6c93e4e8de5", + "size": 4088 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/skills/create", + "url": "https://platform.claude.com/docs/en/api/cli/messages/batches/cancel", "status": "success", - "path": "en/api/go/beta/skills/create.md", - "sha256": "b6b6318cea1688140935c3a9c865dddad70395d537ec4a69ae7bcc3f49770723", - "size": 4201 + "path": "en/api/cli/messages/batches/cancel.md", + "sha256": "55b774905556254ab22c0c5873980544fa6552d320125c338566d7abb26b3eac", + "size": 3739 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/skills/list", + "url": "https://platform.claude.com/docs/en/api/cli/messages/batches/delete", "status": "success", - "path": "en/api/go/beta/skills/list.md", - "sha256": "22626cc502ad898e57ff340d4604baa72ee4ea404ffa7ee56df4c309e5fd80e0", - "size": 4429 + "path": "en/api/cli/messages/batches/delete.md", + "sha256": "7668b24b941d2ce6d50676ce6aa046b5ac48ab67a0b670141123e1513eb4eb36", + "size": 839 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/skills/retrieve", + "url": "https://platform.claude.com/docs/en/api/cli/messages/batches/results", "status": "success", - "path": "en/api/go/beta/skills/retrieve.md", - "sha256": "dd6337154a4c789d2350cdeb04234759cbfb1a79950856a9ebacc769810717ba", - "size": 3966 + "path": "en/api/cli/messages/batches/results.md", + "sha256": "b510a3c30fbe81957449baf2ff01da9067676014515013e5f7088d3897da34cc", + "size": 26319 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/skills/delete", + "url": "https://platform.claude.com/docs/en/api/cli/models", "status": "success", - "path": "en/api/go/beta/skills/delete.md", - "sha256": "36c14b5c2a4ae46381766a65e5671d061cc5e517066deaea750a1294a4f6bdf9", - "size": 3329 + "path": "en/api/cli/models.md", + "sha256": "3936ae0c6e68effff4dfb9120f8bf13886d5b4f0cb9efa6aa494d4a8f1355f22", + "size": 22169 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/skills/versions", + "url": "https://platform.claude.com/docs/en/api/cli/models/list", "status": "success", - "path": "en/api/go/beta/skills/versions.md", - "sha256": "9ca984a37b70d27f15d8a6dfb5b70d65968d2ef511f736c0f25b44016e779830", - "size": 16754 + "path": "en/api/cli/models/list.md", + "sha256": "e974eb880835cd623fa2537e6fc8fd25b864089d5877686a56c5e8239e4fd8d9", + "size": 5915 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/skills/versions/create", + "url": "https://platform.claude.com/docs/en/api/cli/models/retrieve", "status": "success", - "path": "en/api/go/beta/skills/versions/create.md", - "sha256": "99013949cc614f798dd56d6436d3e8733b662d1cdce2ec5de2edb30b6bc806b1", - "size": 4337 + "path": "en/api/cli/models/retrieve.md", + "sha256": "88d62a23096c43ff101df9bc264e0f30818aabae61d43caf96df4af7f2ca71e9", + "size": 4963 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/skills/versions/list", + "url": "https://platform.claude.com/docs/en/api/cli/beta", "status": "success", - "path": "en/api/go/beta/skills/versions/list.md", - "sha256": "86d26523fca63ec7b97d267675b815af883e9924e930f2e0d0f10a0e681d2cdf", - "size": 4394 + "path": "en/api/cli/beta.md", + "sha256": "3e0d7d1f7d3603080757f1e5c94ea8639727aedc38aeb66dd648303f7790dcfc", + "size": 1221715 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/skills/versions/retrieve", + "url": "https://platform.claude.com/docs/en/api/cli/beta/models", "status": "success", - "path": "en/api/go/beta/skills/versions/retrieve.md", - "sha256": "6ccb63e1f62709d752e930e6cb8630a09631abd6830d27020469945adc8efde8", - "size": 4340 + "path": "en/api/cli/beta/models.md", + "sha256": "385ff34a985419069fb011cd7489b161d1b8dbaf856df9beac38784f2158f000", + "size": 22272 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/skills/versions/delete", + "url": "https://platform.claude.com/docs/en/api/cli/beta/models/list", "status": "success", - "path": "en/api/go/beta/skills/versions/delete.md", - "sha256": "7ff09f8a7f41c4acac851cbbe146b06f7958cf5bd5dcbce918568418c2c8d479", - "size": 3668 + "path": "en/api/cli/beta/models/list.md", + "sha256": "5ec77a878ac157492e27f9afdf6277299424ee48854f8be48a4aaf04ec9352af", + "size": 5933 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/user_profiles", + "url": "https://platform.claude.com/docs/en/api/cli/beta/models/retrieve", "status": "success", - "path": "en/api/go/beta/user_profiles.md", - "sha256": "2c31f6bf798c5912c988e15b753b36c9a152fbaa54a9132067c6149817c11c1a", - "size": 18344 + "path": "en/api/cli/beta/models/retrieve.md", + "sha256": "dbbcb4692adbd68f5932caaeeb99d56ed6311af59d0d5344bb7957d5128637d2", + "size": 4978 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/user_profiles/create", + "url": "https://platform.claude.com/docs/en/api/cli/beta/messages", "status": "success", - "path": "en/api/go/beta/user_profiles/create.md", - "sha256": "3ce254c211aaaa022f4d1df1fd4be14decd6f2304f9cccca21dc3863122de92e", - "size": 3592 + "path": "en/api/cli/beta/messages.md", + "sha256": "61490983d6ad378d475ce727d78742bdcce73b4d855207391b8ada6d8db418c5", + "size": 693001 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/user_profiles/list", + "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/create", "status": "success", - "path": "en/api/go/beta/user_profiles/list.md", - "sha256": "c0923abe56005e88dbce50d291b4e04c6a4aed6f71eada040001fb12629f14c8", - "size": 3720 + "path": "en/api/cli/beta/messages/create.md", + "sha256": "e90f974a815c5a0a467016536eeaf21870d0ebd97ea4b755325f36309c0315ba", + "size": 39587 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/user_profiles/retrieve", + "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/count_tokens", "status": "success", - "path": "en/api/go/beta/user_profiles/retrieve.md", - "sha256": "251e45eb64cd687037e607d2ea38f612fcb228235e275123461b68f644ea1e75", - "size": 3332 + "path": "en/api/cli/beta/messages/count_tokens.md", + "sha256": "bd26ee4ac028c5af1c382a377269ff111c9c8e6437352f45371b4d673bebb12f", + "size": 8409 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/user_profiles/update", + "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches", "status": "success", - "path": "en/api/go/beta/user_profiles/update.md", - "sha256": "e13f9645942c208f8dc599c5a76f028a5db7f261d3194b3cffe89d75697a5150", - "size": 3743 + "path": "en/api/cli/beta/messages/batches.md", + "sha256": "28ddb4f4b9219d40a25f479a8df1b2527e0ae409e24b5974720818ecfc9cdc15", + "size": 155556 }, { - "url": "https://platform.claude.com/docs/en/api/go/beta/user_profiles/create_enrollment_url", + "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches/create", "status": "success", - "path": "en/api/go/beta/user_profiles/create_enrollment_url.md", - "sha256": "6f92983fa847fbf6e2788383f886afa91a483764eff941e823ec38bcb7821f57", - "size": 3276 + "path": "en/api/cli/beta/messages/batches/create.md", + "sha256": "334c15f2b78aaad433dcb1436803156de9df3b50a0be27c59db8a2f7522d27a7", + "size": 3820 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/completions", + "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches/retrieve", "status": "success", - "path": "en/api/ruby/completions.md", - "sha256": "55ab13d9e199c646e1ad2eb5f862ac9405e8c6b99e2cba79bd53dacc0375d189", - "size": 11246 + "path": "en/api/cli/beta/messages/batches/retrieve.md", + "sha256": "08ecbfd6afb427400990a03e6532d20a30f20aa660ffb42e4bfd41916aea7581", + "size": 3554 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/completions/create", + "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches/list", "status": "success", - "path": "en/api/ruby/completions/create.md", - "sha256": "0d76f1a8265f52f42d6e64c26c73073181c92fa476102fc1e8a4875dc67d18f7", - "size": 8723 + "path": "en/api/cli/beta/messages/batches/list.md", + "sha256": "c6ef13fa77b5b094f1e09a77574881cdad3c428cf1bbfababb3484c2ca2d7db0", + "size": 4271 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/messages", + "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches/cancel", "status": "success", - "path": "en/api/ruby/messages.md", - "sha256": "37e938263d1434bc91a13b99a593bc0119faa8c613dd40063183b5b3b49a97b7", - "size": 818551 + "path": "en/api/cli/beta/messages/batches/cancel.md", + "sha256": "5f2508da1ca9906ac68fa76f851ac067730c9ad85ca761cc9e267e2661af60fc", + "size": 3866 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/messages/create", + "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches/delete", "status": "success", - "path": "en/api/ruby/messages/create.md", - "sha256": "50353a7a6f3a7ae5fc2e428ca476de9471b761d31ba0e4dc377fe49f32ca0353", - "size": 111712 + "path": "en/api/cli/beta/messages/batches/delete.md", + "sha256": "00d17c475dba95e4903b39db5fd8eb4e9f770fb028c8c3aff178fd9bccc608eb", + "size": 966 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches/results", "status": "success", - "path": "en/api/ruby/messages/count_tokens.md", - "sha256": "454842e7ead1f964d612d3881b4a12119966ce2171cdeac02b128c7bb9ace1e5", - "size": 88135 + "path": "en/api/cli/beta/messages/batches/results.md", + "sha256": "305bbd9a506c3d308e11a8bd1da0a8ccd42f39396c23c2f7032b302f1b38b70a", + "size": 35538 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches", + "url": "https://platform.claude.com/docs/en/api/cli/beta/agents", "status": "success", - "path": "en/api/ruby/messages/batches.md", - "sha256": "2b77b0d9d97712781028e775a70da1ab3ec44a2c395f956fabedce250f454036", - "size": 218761 + "path": "en/api/cli/beta/agents.md", + "sha256": "be5773e1e8020949ab2d736e7f1d8b113fcd6ef03f05383aff32fbf05af77a2b", + "size": 78677 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/cli/beta/agents/create", "status": "success", - "path": "en/api/ruby/messages/batches/create.md", - "sha256": "52a683406a3a58d90729c58129188755f6d73e85af6ad9af7188229826135f94", - "size": 102465 + "path": "en/api/cli/beta/agents/create.md", + "sha256": "680366fac3ab1ddc48fd26711ffe63a0563e8128c8e5940aebf89987a3fc8b64", + "size": 8598 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/cli/beta/agents/list", "status": "success", - "path": "en/api/ruby/messages/batches/retrieve.md", - "sha256": "2792a2109abb099151501bf269e767895dc3e80e1d8a8362cb73367ee34b6948", - "size": 3469 + "path": "en/api/cli/beta/agents/list.md", + "sha256": "411152079ae8bf2f20a1776de18da702759353d9b45e8964f733d32d36a81a5e", + "size": 8210 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/cli/beta/agents/retrieve", "status": "success", - "path": "en/api/ruby/messages/batches/list.md", - "sha256": "a51fbb8269d344d6ddcf0f92c4b2a5849e94a4fde37714cf83fc7a5254262e61", - "size": 3663 + "path": "en/api/cli/beta/agents/retrieve.md", + "sha256": "88d1fef65a29c88a6cc513b96fa5a7ebdfe970624bbf997e6a91b0546654815d", + "size": 7500 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/cli/beta/agents/update", "status": "success", - "path": "en/api/ruby/messages/batches/cancel.md", - "sha256": "c95b6e6aab5e4af187c2e0060fdcfecc71acd179499bf1b56c8e0c3b78db9b1f", - "size": 3781 + "path": "en/api/cli/beta/agents/update.md", + "sha256": "783932565a8dda4e5770c2f80f2b60478757a0401c7bc9da6d34e5030d1ebe8c", + "size": 9301 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/cli/beta/agents/archive", "status": "success", - "path": "en/api/ruby/messages/batches/delete.md", - "sha256": "58810ae26925e085742e6cc18a21a0c5b45ad8de4cea42d7828dfb3ff0a97e7f", - "size": 980 + "path": "en/api/cli/beta/agents/archive.md", + "sha256": "1976a444f8a9db8a560b629b05f9492704d49ed892b78d4e2b8f15e2a1e74f16", + "size": 7354 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/cli/beta/agents/versions", "status": "success", - "path": "en/api/ruby/messages/batches/results.md", - "sha256": "4a9e660e591ce459cf1e867a094de078ceb981dbeb3ee1e99de1e5bfd398a631", - "size": 26763 + "path": "en/api/cli/beta/agents/versions.md", + "sha256": "e85655ff9ae416933f42403aa5135fc9b40708cff3695df2dcfa5d122e1e35c2", + "size": 8029 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/models", + "url": "https://platform.claude.com/docs/en/api/cli/beta/agents/versions/list", "status": "success", - "path": "en/api/ruby/models.md", - "sha256": "60fc859dace3b5661822dcee745c7c2c2a82225250e397f3e6fb93c0f889a5da", - "size": 22303 + "path": "en/api/cli/beta/agents/versions/list.md", + "sha256": "f418019f97de37f6027853d8d63b0ea9bf4fa8cd37a4637e01b0e0b660047f52", + "size": 8017 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/models/list", + "url": "https://platform.claude.com/docs/en/api/cli/beta/environments", "status": "success", - "path": "en/api/ruby/models/list.md", - "sha256": "4ced60416d908e8ef2286c95dad130abe68d352bbb78112b160c3c3b3762db4d", - "size": 6066 + "path": "en/api/cli/beta/environments.md", + "sha256": "0bb5efafae69bd81d9faad0a15ef417613db5a366c7273625f68426cfda700c4", + "size": 26374 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/cli/beta/environments/create", "status": "success", - "path": "en/api/ruby/models/retrieve.md", - "sha256": "11a3bcdf16cd009b2b45fc5f2d586a3c424dcb169e2c3c0edad117c485b4c1b0", - "size": 5737 + "path": "en/api/cli/beta/environments/create.md", + "sha256": "95c9050cef72fe23911b73f6042b6503b9cdc4d753306cc7fb09ccc2b80fe15b", + "size": 3289 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta", + "url": "https://platform.claude.com/docs/en/api/cli/beta/environments/list", "status": "success", - "path": "en/api/ruby/beta.md", - "sha256": "03af74df8881e2324e0def7af4ae51136e5819e33de75dd15f9a31c64caa2196", - "size": 1087233 + "path": "en/api/cli/beta/environments/list.md", + "sha256": "6731b616a561ba0e7184ebb25076af025cd24a68216ccfb0a531e375fa04ee88", + "size": 3573 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/models", + "url": "https://platform.claude.com/docs/en/api/cli/beta/environments/retrieve", "status": "success", - "path": "en/api/ruby/beta/models.md", - "sha256": "14b821d04dc2699cccf9a840a03eda6e190970eec39e02cf317bf5921cb73d65", - "size": 22776 + "path": "en/api/cli/beta/environments/retrieve.md", + "sha256": "b1cea8a77d98830184054330e7a4299e8b36fd2c7591888df6e19d5ab109ad00", + "size": 2852 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/models/list", + "url": "https://platform.claude.com/docs/en/api/cli/beta/environments/update", "status": "success", - "path": "en/api/ruby/beta/models/list.md", - "sha256": "5dfe1f301ab8a05cc0e732961788e5738e8273775aa59f1e9c52a14c9fc9553f", - "size": 6164 + "path": "en/api/cli/beta/environments/update.md", + "sha256": "d78c270b79eed2a9b34485d4f0ccf7e0de2df8484846a560e34f4ca97c8e4b21", + "size": 3414 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/cli/beta/environments/delete", "status": "success", - "path": "en/api/ruby/beta/models/retrieve.md", - "sha256": "071a384cb6b33691536c5b374bbe5b1c520e634929fb3e022a67c3a7cde719d9", - "size": 5845 + "path": "en/api/cli/beta/environments/delete.md", + "sha256": "c517e564e3f32013663fc411666e3552a216c0976a0fbdb06c225f4f9c1ade4a", + "size": 681 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages", + "url": "https://platform.claude.com/docs/en/api/cli/beta/environments/archive", "status": "success", - "path": "en/api/ruby/beta/messages.md", - "sha256": "bceabf88487bbd9b50f4ca03464c82e35f90c02582e11993dd15d3b925a3ee5f", - "size": 1013377 + "path": "en/api/cli/beta/environments/archive.md", + "sha256": "671d7c4962724f81fe558fbc56b41a1ab2700185dc4d18a160afe394ce0ff9cb", + "size": 2910 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/create", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions", "status": "success", - "path": "en/api/ruby/beta/messages/create.md", - "sha256": "74cf23d6a9d566fb2513276b4a8c9dda33b47fe77f1fe0f077a95e53e1b165d3", - "size": 140477 + "path": "en/api/cli/beta/sessions.md", + "sha256": "6b973b9f793dd32e616a13672dbf6e900977696bb05e20b614cc2ff94cce7d85", + "size": 333479 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/create", "status": "success", - "path": "en/api/ruby/beta/messages/count_tokens.md", - "sha256": "4abe48483ebee5f75c8935f171c51a82f95567765a92461db5f9de576ff5cdae", - "size": 108731 + "path": "en/api/cli/beta/sessions/create.md", + "sha256": "e2bbff0c12865725d823bc672611c5eebb2798246e59b9e77c868e995fbfd87d", + "size": 11473 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/list", "status": "success", - "path": "en/api/ruby/beta/messages/batches.md", - "sha256": "3d4f218a3a52ef503a206ccb6ad612f3e85be40aa8c72b8208df4f3cd4f2cd1d", - "size": 281076 + "path": "en/api/cli/beta/sessions/list.md", + "sha256": "8cef3b6445d7af0250068e81f922f9c3ec4ae67195ccae9bc32e536439f2ebb1", + "size": 12202 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/retrieve", "status": "success", - "path": "en/api/ruby/beta/messages/batches/create.md", - "sha256": "a0869ab7b1cd6dc36eada50fb1b50afd8e7199d3c02c67e2af3eb55922c0b977", - "size": 125223 + "path": "en/api/cli/beta/sessions/retrieve.md", + "sha256": "d3ac2a479ff03f5e17914298e7a005aecb4140211d692258dbc783e8e6e71a39", + "size": 10615 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/update", "status": "success", - "path": "en/api/ruby/beta/messages/batches/retrieve.md", - "sha256": "566367f8552cea57741d1e9b847f72b2c1bea0fe588074e56f72b968236eee6c", - "size": 4557 + "path": "en/api/cli/beta/sessions/update.md", + "sha256": "95ca9252e804372e24efe865f30cc8a59f7869857c6af0bb973f032b9a4bd268", + "size": 11061 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/delete", "status": "success", - "path": "en/api/ruby/beta/messages/batches/list.md", - "sha256": "5962d80833f8293b894b1af73c9f6e17cd82fb5135fd58f3be22d10a7a4835e1", - "size": 4731 + "path": "en/api/cli/beta/sessions/delete.md", + "sha256": "8e627406a19efed22c9962e3046c1657bc7c3be12e329444328662bf9d55744d", + "size": 625 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/archive", "status": "success", - "path": "en/api/ruby/beta/messages/batches/cancel.md", - "sha256": "683cc517dec83b8c16243ce65696c6bb61168fe577a3737658b593cabacc8993", - "size": 4869 + "path": "en/api/cli/beta/sessions/archive.md", + "sha256": "1ef9c3628534874b6d15a986b5ba75b6e3ec12c1fb7a75196b9f1eb598cb0946", + "size": 10625 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/events", "status": "success", - "path": "en/api/ruby/beta/messages/batches/delete.md", - "sha256": "7dd803dad1195a75e9f23e40925ef5630813dd7aa0db98ad87e6b1de4aee8919", - "size": 2064 + "path": "en/api/cli/beta/sessions/events.md", + "sha256": "522fe555e16ec20d424a915851f2d17f4d8c5eb580710afebefdec869b4c2fed", + "size": 244487 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/events/list", "status": "success", - "path": "en/api/ruby/beta/messages/batches/results.md", - "sha256": "68f7fe20a12efb54b684ab327af5ab65fdf9c7f97b8cc9f8d07f84dd8fd9539d", - "size": 36598 + "path": "en/api/cli/beta/sessions/events/list.md", + "sha256": "a9343f872e1836547e6ef4a44985d5f0a42d6175e7f24311d060bf5dbfd7f014", + "size": 39257 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/files", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/events/send", "status": "success", - "path": "en/api/ruby/beta/files.md", - "sha256": "f28d82294b7e99f71a68cb54e8b609a4a22684039f370d52d9fc3f3dea5cca1a", - "size": 10193 + "path": "en/api/cli/beta/sessions/events/send.md", + "sha256": "1855105335ffa7445f2696e04c5c3cc8e9c0c63bfadb4e532e7c82583c5250e3", + "size": 11078 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/files/upload", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/events/stream", "status": "success", - "path": "en/api/ruby/beta/files/upload.md", - "sha256": "c1f3e45e1485d2f976089416d85e3ae17273651bd1d0abeca6385f3ebcb368b4", - "size": 1987 + "path": "en/api/cli/beta/sessions/events/stream.md", + "sha256": "e9bb0a41602dafc4c0e313b2c633e31dc5dcd8ae7f2af84d81f8122530031b07", + "size": 37458 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/files/list", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/resources", "status": "success", - "path": "en/api/ruby/beta/files/list.md", - "sha256": "31c6f205d0a6e7302c692668d9276d40583eacbd5b73d1bb430fd9d7b8268e4c", - "size": 2302 + "path": "en/api/cli/beta/sessions/resources.md", + "sha256": "6eedc29a15b6e31a6e932db393800c8b9721f64be42e6569f9613c1f60d987bb", + "size": 11060 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/files/download", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/resources/add", "status": "success", - "path": "en/api/ruby/beta/files/download.md", - "sha256": "b24ba891341b98acb90d1b241e4a3b0c37924551b6a8e1f8abc62f6ed8d27422", - "size": 1432 + "path": "en/api/cli/beta/sessions/resources/add.md", + "sha256": "1a6a99445e3b566ed0453fcabf4baa68bb03df367fdf8e5524c5452c44648988", + "size": 1076 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/files/retrieve_metadata", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/resources/list", "status": "success", - "path": "en/api/ruby/beta/files/retrieve_metadata.md", - "sha256": "bff45ef370f258a7bf1e0adea836d7e9f345cce68c74603f7c99ca6203af3bea", - "size": 2019 + "path": "en/api/cli/beta/sessions/resources/list.md", + "sha256": "27007e7fa6fe41eed7e2a9eb9ca6f0d46993f63be56fc48d89fc1635f4780bb5", + "size": 2285 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/files/delete", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/resources/retrieve", "status": "success", - "path": "en/api/ruby/beta/files/delete.md", - "sha256": "ebee7e937fcf30e5f1a5a0eba4fdad3e1f96ca6e5af7a7352d7808680408deeb", - "size": 1619 + "path": "en/api/cli/beta/sessions/resources/retrieve.md", + "sha256": "50731264e315acbb0f7adea9154a79ca79b611e94be62ab1327fc4414df71e6b", + "size": 1934 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/resources/update", "status": "success", - "path": "en/api/ruby/beta/skills.md", - "sha256": "204953f3172a3303e7d739724d53ad5d63430bb1c7448009c40ada6d25867ff2", - "size": 26048 + "path": "en/api/cli/beta/sessions/resources/update.md", + "sha256": "9b545ddf98ddc6a839e8d3c357945f5fca050c1648569ddca3b001046d2e8f0a", + "size": 2137 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/create", + "url": "https://platform.claude.com/docs/en/api/cli/beta/sessions/resources/delete", "status": "success", - "path": "en/api/ruby/beta/skills/create.md", - "sha256": "37b10923510435674ddb5cc2279e0e62066fd72a61a1bdea5d544392815a33c1", - "size": 2572 + "path": "en/api/cli/beta/sessions/resources/delete.md", + "sha256": "3b1c71ebc944de47fc103acfab6515dec1fef66e783b6752bce5856aef67e4a4", + "size": 824 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/list", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults", "status": "success", - "path": "en/api/ruby/beta/skills/list.md", - "sha256": "9fd3d3c58685134308468a6b508da42d6e3a663796ad507940f84bb89957dafe", - "size": 2748 + "path": "en/api/cli/beta/vaults.md", + "sha256": "8868e2068a66b46a400c9350831dc4782d7c6e2b99ae0f90abf9eb10258407d0", + "size": 44281 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/retrieve", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/create", "status": "success", - "path": "en/api/ruby/beta/skills/retrieve.md", - "sha256": "bc3c590734007f10202c10f349f92b6fa6fa3864f3a1c63005a048c62f8aa4e7", - "size": 2399 + "path": "en/api/cli/beta/vaults/create.md", + "sha256": "8af0a88a59a12f966f21d54139fb4d99e3e859f08386884c2aa0fdd0e1e0d8d7", + "size": 1134 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/delete", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/list", "status": "success", - "path": "en/api/ruby/beta/skills/delete.md", - "sha256": "86cb76d854f1b05906285aa199bb28f96e60253b97ad103f734e0fb3dfdf1821", - "size": 1729 + "path": "en/api/cli/beta/vaults/list.md", + "sha256": "13d2dea190fcb12bf4e68ff107d357ea6acbb64324fd8a595ea13ab02ac4f8d6", + "size": 1404 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/versions", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/retrieve", "status": "success", - "path": "en/api/ruby/beta/skills/versions.md", - "sha256": "15dba608e8a8b57f89f444bdc573aee310d86ae7fece14e0b7fc10c7d7d7ad09", - "size": 13503 + "path": "en/api/cli/beta/vaults/retrieve.md", + "sha256": "8bb9d888a5e077bc2aad983953cd2c286b4c45e382743583a85858a509940c87", + "size": 991 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/versions/create", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/update", "status": "success", - "path": "en/api/ruby/beta/skills/versions/create.md", - "sha256": "0c79efb2951d95feee19c4365cac8e24697519b4ae793fe4212cb4d58853beda", - "size": 2696 + "path": "en/api/cli/beta/vaults/update.md", + "sha256": "146f123e8137e233114ebbc8e32cb15cff0a973ebb99ba0c97f180dcf0b1f506", + "size": 1286 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/versions/list", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/delete", "status": "success", - "path": "en/api/ruby/beta/skills/versions/list.md", - "sha256": "b8c696d598618b3106b16c0c9c6cda506825acbf05616b8cf335f788cde19375", - "size": 2709 + "path": "en/api/cli/beta/vaults/delete.md", + "sha256": "fc20c485b600a9ff1c684085305852dabd6c8618b191ef23347999170824b34d", + "size": 620 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/versions/retrieve", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/archive", "status": "success", - "path": "en/api/ruby/beta/skills/versions/retrieve.md", - "sha256": "1a686446bdf27a7d115513754e7a744be1ae4dab818c2283e43e7c6411d576f0", - "size": 2697 + "path": "en/api/cli/beta/vaults/archive.md", + "sha256": "fb33b123f3dd4d1ddc7527d5bb950b3333ec996294d1ccc2ab00aa39e0d68dd8", + "size": 1001 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/skills/versions/delete", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/credentials", "status": "success", - "path": "en/api/ruby/beta/skills/versions/delete.md", - "sha256": "fba18b492aafa54d7adae0230038415e9d644dbb85513344bf5a47fecaa5bfff", - "size": 1991 + "path": "en/api/cli/beta/vaults/credentials.md", + "sha256": "5a36da6e49d0bcbca2623342c60b8549461db31f83a9fcb24a25fb0133965614", + "size": 36945 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/user_profiles", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/credentials/create", "status": "success", - "path": "en/api/ruby/beta/user_profiles.md", - "sha256": "79f471b20b18d96dc9c34a36fe0bc5e05f37b40c0fc279209881c1bd784f084d", - "size": 10010 + "path": "en/api/cli/beta/vaults/credentials/create.md", + "sha256": "04e9615c9cae83f8b63a5d43c0bda356b0620409cf9d7b6ed1c1668379d4ff6f", + "size": 4021 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/user_profiles/create", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/credentials/list", "status": "success", - "path": "en/api/ruby/beta/user_profiles/create.md", - "sha256": "943657d08d5e83c83f94db5a6d1a4e71a9b7e9f8bda2c5763ecc78c5cbe434e8", - "size": 1960 + "path": "en/api/cli/beta/vaults/credentials/list.md", + "sha256": "fac330d176984ab9dc7739ed67d86429c52f8dc5c7735e47b628511d5fecb54f", + "size": 4116 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/user_profiles/list", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/credentials/retrieve", "status": "success", - "path": "en/api/ruby/beta/user_profiles/list.md", - "sha256": "ec80d444b1dac84d66f53871efc6e7b32b9d3036640b858dd31322045fcdc013", - "size": 1879 + "path": "en/api/cli/beta/vaults/credentials/retrieve.md", + "sha256": "199b5e8b19196fe643e8604a367c3aebd1948db5437e972b9b9d148744545b3e", + "size": 3645 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/user_profiles/retrieve", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/credentials/update", "status": "success", - "path": "en/api/ruby/beta/user_profiles/retrieve.md", - "sha256": "2809fe1281946c8200c6bfb44cf67f6b5c748917e8e60c7d3d125f2c4ce40471", - "size": 1758 + "path": "en/api/cli/beta/vaults/credentials/update.md", + "sha256": "5a003a3913c65e7dc99f1d973f1b19dc163b14513caac0c2189bb90317e27081", + "size": 4088 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/user_profiles/update", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/credentials/delete", "status": "success", - "path": "en/api/ruby/beta/user_profiles/update.md", - "sha256": "b0b4badf5a0b1f1f25be45a5a43704250ab903cc0a956aaa5761d0d6bd288868", - "size": 2081 + "path": "en/api/cli/beta/vaults/credentials/delete.md", + "sha256": "9b8d5c30f37b01e891756cfffe1188242033c335d210965a7392b5c95c4c0174", + "size": 863 }, { - "url": "https://platform.claude.com/docs/en/api/ruby/beta/user_profiles/create_enrollment_url", + "url": "https://platform.claude.com/docs/en/api/cli/beta/vaults/credentials/archive", "status": "success", - "path": "en/api/ruby/beta/user_profiles/create_enrollment_url.md", - "sha256": "781a98856d1386d7a4af5435d4a9584c5b3ae4cf8a7813ec662a609f99a52bec", - "size": 1665 + "path": "en/api/cli/beta/vaults/credentials/archive.md", + "sha256": "f0deab75d34d81c789356537246b4f153f3d582affed2adec5e1b8f065ea4b9a", + "size": 3655 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/completions", + "url": "https://platform.claude.com/docs/en/api/cli/beta/files", "status": "success", - "path": "en/api/terraform/completions.md", - "sha256": "6678c94d32a5c4320cc37cd3357050f89c30c09ce707583070525aa71caa8470", - "size": 91179 + "path": "en/api/cli/beta/files.md", + "sha256": "7d1f431d0f29883a3a3ad1982995741c79ee6bb17b0b7d8d4cdacdb77658bf26", + "size": 7194 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/completions/create", + "url": "https://platform.claude.com/docs/en/api/cli/beta/files/upload", "status": "success", - "path": "en/api/terraform/completions/create.md", - "sha256": "fcd219f162f4fab53f2e8f786c6bdaa9032bcb23ab9c394017a9807dceed8960", - "size": 91204 + "path": "en/api/cli/beta/files/upload.md", + "sha256": "dbe80d4a4c51d0f3fa231dde0338c3f86f6ba1acd7bce9c08068d7283784d4c5", + "size": 1283 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/messages", + "url": "https://platform.claude.com/docs/en/api/cli/beta/files/list", "status": "success", - "path": "en/api/terraform/messages.md", - "sha256": "762239bf84e511ea341620e48c2e24202b7e1b2fc61aac1e7775e02687bf9c4f", - "size": 91170 + "path": "en/api/cli/beta/files/list.md", + "sha256": "be1465bc8a05ff8226f545c8663fdc73c0920fbce5191608c8f8159c041793b3", + "size": 2193 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/messages/create", + "url": "https://platform.claude.com/docs/en/api/cli/beta/files/download", "status": "success", - "path": "en/api/terraform/messages/create.md", - "sha256": "7555cbf37b7db79760d68cdcc6c7364002c4e23369828df5bbc0fb1f71f243a5", - "size": 91195 + "path": "en/api/cli/beta/files/download.md", + "sha256": "c3f94484cd1c23d8c3b1b04dba6feef0e5b20c2acea8bcd4d43c5f26333c3cb0", + "size": 417 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/cli/beta/files/retrieve_metadata", "status": "success", - "path": "en/api/terraform/messages/count_tokens.md", - "sha256": "d1b98380dbff4cca5924ac3307223a25fc7bbde562e304235f767da100b26e56", - "size": 91213 + "path": "en/api/cli/beta/files/retrieve_metadata.md", + "sha256": "9eddf253740d0778325b557fbc9d39ca4a990de8f481b79b074bb56333e6d6ce", + "size": 1301 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches", + "url": "https://platform.claude.com/docs/en/api/cli/beta/files/delete", "status": "success", - "path": "en/api/terraform/messages/batches.md", - "sha256": "242ae268638d10fa4a63714f50306ac9bf3ea3252e729586436b70b72174bb27", - "size": 91198 + "path": "en/api/cli/beta/files/delete.md", + "sha256": "c02f26c5212ae8da02ca65103c5d7888adce4950ce7cc1e87a53764b696d7854", + "size": 601 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/cli/beta/skills", "status": "success", - "path": "en/api/terraform/messages/batches/create.md", - "sha256": "6f88ae79018ffa3f136109dd075821588bf1991f2cc6b8d624e9d5c014b2cad9", - "size": 91223 + "path": "en/api/cli/beta/skills.md", + "sha256": "6f5dd1254ed808d66df672f2c629f38aad6c917259d54637b161bbd181b82976", + "size": 12745 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/create", "status": "success", - "path": "en/api/terraform/messages/batches/retrieve.md", - "sha256": "cb49609109b00263dd709e47c3fce1b5d1c5f07a5080316be5cf93caf3bba5ac", - "size": 91229 + "path": "en/api/cli/beta/skills/create.md", + "sha256": "cca94e3dae7e858d91a1ebbbc741533ea5f94492f0be063b171a71bc941e94f7", + "size": 1635 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/list", "status": "success", - "path": "en/api/terraform/messages/batches/list.md", - "sha256": "6f3f48a6a9c62c47f362008d9325c0cc06fcfbe8bdfda9d444eab9486ebb29f9", - "size": 91217 + "path": "en/api/cli/beta/skills/list.md", + "sha256": "8f25a728c06b5ec690aeffc3a935f2c86681fae20d161fee3d534355ccb54dc3", + "size": 2335 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/retrieve", "status": "success", - "path": "en/api/terraform/messages/batches/cancel.md", - "sha256": "2b80a0940506974d7f64b9efd078308003f779a0992d8f2eeaed7a3a27a79b1e", - "size": 91223 + "path": "en/api/cli/beta/skills/retrieve.md", + "sha256": "f0d1d64d5680062d28ab7eb64b9d2af35bb66c5538dbfbe4b9bb7dc48a625bd0", + "size": 1401 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/delete", "status": "success", - "path": "en/api/terraform/messages/batches/delete.md", - "sha256": "b951c996f42ba5e27b960e7f4b8481f846ca4af51e8325dc4a8f6d7453c9c390", - "size": 91223 + "path": "en/api/cli/beta/skills/delete.md", + "sha256": "504871ca400a1b6790177235cbf84722468ed820eda734c385bacec70d9747ba", + "size": 709 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/versions", "status": "success", - "path": "en/api/terraform/messages/batches/results.md", - "sha256": "6307c31cc6b6ff6a019048725a4783de084bdb7699d208bd89c13e0e9caa94c4", - "size": 91226 + "path": "en/api/cli/beta/skills/versions.md", + "sha256": "9f0e17a5ba14d03aec5d7486719c5240192dbf8df857450a3a72b315798e3b13", + "size": 6651 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/models", + "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/versions/create", "status": "success", - "path": "en/api/terraform/models.md", - "sha256": "db425a8bc331e03c382a125997ce1c3942b655a75537fe36fa3a24be0f313461", - "size": 91164 + "path": "en/api/cli/beta/skills/versions/create.md", + "sha256": "3e91a54c1fa92b907c699bef6be89e61ac19c5fbdee5a24654f03f979fc827e0", + "size": 1749 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/models/list", + "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/versions/list", "status": "success", - "path": "en/api/terraform/models/list.md", - "sha256": "a5e7d86db9597949b88e0b5b695ef61d76fc59911dc8098f2950e7101ad6f5db", - "size": 91183 + "path": "en/api/cli/beta/skills/versions/list.md", + "sha256": "ed1a396d969e14e1bf275e06836ab036d1334f6457a4482d0ad16d9105244171", + "size": 2137 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/versions/retrieve", "status": "success", - "path": "en/api/terraform/models/retrieve.md", - "sha256": "3fa53d6a2be359d09d17a4ea26007407cd3fd45d69881e2dab500e53696f1e5a", - "size": 91195 + "path": "en/api/cli/beta/skills/versions/retrieve.md", + "sha256": "494dfec345521d1c781e547046e94627723414b83019687aadb48f7f901e53e6", + "size": 1738 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta", + "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/versions/delete", "status": "success", - "path": "en/api/terraform/beta.md", - "sha256": "a61864a161c1b335a3b7c64b87e3b000928b157492cdc7c9328b9d4e6114eca7", - "size": 91158 + "path": "en/api/cli/beta/skills/versions/delete.md", + "sha256": "75496fd34da360eafb2c74e603a1374ec1bda86a5d4f96dd18196143cc49d7f6", + "size": 1012 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/models", + "url": "https://platform.claude.com/docs/en/api/php/completions", "status": "success", - "path": "en/api/terraform/beta/models.md", - "sha256": "81a6d2a78345503a107a3e92dc27684cc83eb50b887c53b5fbc310285e9a62ba", - "size": 91183 + "path": "en/api/php/completions.md", + "sha256": "ea546563214219672c5287504979dc21259e3867da616c8e1b5ffb91b2980d99", + "size": 89188 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/models/list", + "url": "https://platform.claude.com/docs/en/api/php/completions/create", "status": "success", - "path": "en/api/terraform/beta/models/list.md", - "sha256": "b9f61e33f9d1f1013438d7ae925533462f25ceb1807488c3c56b49ba6af087fd", - "size": 91202 + "path": "en/api/php/completions/create.md", + "sha256": "4669086173a554ab6de65299a9199af830ffdf5f0c8e3f3e07ef06d7527d59f3", + "size": 89213 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/php/messages", "status": "success", - "path": "en/api/terraform/beta/models/retrieve.md", - "sha256": "17c2a0aa3b90061bd7c1cff42ac7fe98adeae958e481a916baec866369c45dac", - "size": 91214 + "path": "en/api/php/messages.md", + "sha256": "0cebf4c873b5fb043140fefb9c40e4df881f065be99c8f8890a060c5637b972b", + "size": 89179 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages", + "url": "https://platform.claude.com/docs/en/api/php/messages/create", "status": "success", - "path": "en/api/terraform/beta/messages.md", - "sha256": "2047f58f066161609e7b7bed8a60d424d578318b9e92506111252a511d63fa5e", - "size": 91189 + "path": "en/api/php/messages/create.md", + "sha256": "c7aaedd406f65c25533aec136a556dfaedb702b3cdb05b34bbe09b240124b700", + "size": 89204 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/create", + "url": "https://platform.claude.com/docs/en/api/php/messages/count_tokens", "status": "success", - "path": "en/api/terraform/beta/messages/create.md", - "sha256": "744ff7b27eb9e4049b2823ce0df0cb17c79d80ba003ab9c2f2c4579f72f75e61", - "size": 91214 + "path": "en/api/php/messages/count_tokens.md", + "sha256": "91d524c16d5fc374ca7330b1f1894af08fc03e84c02d9ebf3ba846223d9974ad", + "size": 89222 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/php/messages/batches", "status": "success", - "path": "en/api/terraform/beta/messages/count_tokens.md", - "sha256": "9e911be1803655b6ccd5f18a43b33c7c93acc13545bd2572fa291d259be6fc25", - "size": 91232 + "path": "en/api/php/messages/batches.md", + "sha256": "938b6bf4dafb417cbfbfe29fb4296ee991050f7335a832aa4711745b98e7a281", + "size": 89207 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches", + "url": "https://platform.claude.com/docs/en/api/php/messages/batches/create", "status": "success", - "path": "en/api/terraform/beta/messages/batches.md", - "sha256": "4ea7bc3d71e0a23a3b90ff033184075aea965112879f8cb0a4b373c7f4abdb8e", - "size": 91217 + "path": "en/api/php/messages/batches/create.md", + "sha256": "5d58ac95ba86a2ba8527560ceabd99e4fc63f0dd82047bf1b02eedda6885936d", + "size": 89232 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/php/messages/batches/retrieve", "status": "success", - "path": "en/api/terraform/beta/messages/batches/create.md", - "sha256": "5d28720281c2c46c933acf5170085d893aee6deb757efff6f906e8e1607622b7", - "size": 91242 + "path": "en/api/php/messages/batches/retrieve.md", + "sha256": "d8111a231b9b6abc34e05c874aa32822290ffad2206f11fa62f7dffb87c5384f", + "size": 89238 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/php/messages/batches/list", "status": "success", - "path": "en/api/terraform/beta/messages/batches/retrieve.md", - "sha256": "eec62699e83c2ddb3be66a7cfb91bf5a95a7dce6e7c133c81a682eb64a1b3f61", - "size": 91248 + "path": "en/api/php/messages/batches/list.md", + "sha256": "c22030b2a7e97148f4a8ae123360ea901b8d719ed56b026f5db4ec0ed2dec88b", + "size": 89226 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/php/messages/batches/cancel", "status": "success", - "path": "en/api/terraform/beta/messages/batches/list.md", - "sha256": "fad0525ae9ee2e3689b25b8687cbb2838ca9ad916db7547e839f73db931e0c56", - "size": 91236 + "path": "en/api/php/messages/batches/cancel.md", + "sha256": "cd4f4b1e8ba214e15e2e15e9f280c80325884ea806b96deca603111616752b95", + "size": 89232 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/php/messages/batches/delete", "status": "success", - "path": "en/api/terraform/beta/messages/batches/cancel.md", - "sha256": "7eeb361c2bd5373db0dd02214c04eac71cc864e9e1dc52c02b6b1fe3b86e54c0", - "size": 91242 + "path": "en/api/php/messages/batches/delete.md", + "sha256": "9bd8b89b44556393c900e628a4e4056ae54a643530ef5b4eba36a104c09c2a0e", + "size": 89232 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/php/messages/batches/results", "status": "success", - "path": "en/api/terraform/beta/messages/batches/delete.md", - "sha256": "fb0e5e85a7e0aee71da4a3e1f0c9fa8def3b0fb54380cb7541574b4d9d4be482", - "size": 91242 + "path": "en/api/php/messages/batches/results.md", + "sha256": "175f7970bfc7ad3b3d268348b6d9dbdb7e5995eb39b0bc55eb8349c95d03d29b", + "size": 89235 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/php/models", "status": "success", - "path": "en/api/terraform/beta/messages/batches/results.md", - "sha256": "ba8e5985f08c3bd2d3b9191323502276a3cd5533cff0fa11eca7f1ae4278cbf6", - "size": 91245 + "path": "en/api/php/models.md", + "sha256": "1c150de3280c17ec5a4c3145082d62381409fe991d29919cbba230c82b6faf01", + "size": 89173 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/files", + "url": "https://platform.claude.com/docs/en/api/php/models/list", "status": "success", - "path": "en/api/terraform/beta/files.md", - "sha256": "f2a9076b63e48cfb8632ba5fbc02c9dd1e3dfc198c2ed64c9803ed5861ab0fcf", - "size": 91180 + "path": "en/api/php/models/list.md", + "sha256": "de47771fa3ce0c80a6ae367884096c754f27287a8d6ef4f7e35f70281f6fad7e", + "size": 89192 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/files/upload", + "url": "https://platform.claude.com/docs/en/api/php/models/retrieve", "status": "success", - "path": "en/api/terraform/beta/files/upload.md", - "sha256": "1e3bdf5f5b26d7c31d4cd04313ae4fc41db94a75556079f4846f949b166395fa", - "size": 91205 + "path": "en/api/php/models/retrieve.md", + "sha256": "a4ea5d38e7b163c1eb9cb054553af00aeca3b0374d77310765ff1dabeacda428", + "size": 89204 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/files/list", + "url": "https://platform.claude.com/docs/en/api/php/beta", "status": "success", - "path": "en/api/terraform/beta/files/list.md", - "sha256": "d106a278dac839487256c1c7f8af0f5247781659458be53ec0216570992d53b5", - "size": 91199 + "path": "en/api/php/beta.md", + "sha256": "2ddfafda96c59754e635d516a1777f6ca20b777aaf5cef5be1a2b1e5e14ed15a", + "size": 89167 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/files/download", + "url": "https://platform.claude.com/docs/en/api/php/beta/models", "status": "success", - "path": "en/api/terraform/beta/files/download.md", - "sha256": "eba899b90051b53e2d847464b5bafe09dd29ec07b7155b2314d569a4c01586a1", - "size": 91211 + "path": "en/api/php/beta/models.md", + "sha256": "96b9595ad16d9cdecff3458b1fadba8de2738dd3c30d9d2c963acd63b8f77452", + "size": 89192 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/files/retrieve_metadata", + "url": "https://platform.claude.com/docs/en/api/php/beta/models/list", "status": "success", - "path": "en/api/terraform/beta/files/retrieve_metadata.md", - "sha256": "8a08483febd9368cc2cb8de5b431310e4a1d22c0c02245f90134f76441592f6f", - "size": 91238 + "path": "en/api/php/beta/models/list.md", + "sha256": "74ed574540beab37fdc47c5d6e373de354ce29e509b1e973462a94d2d90c4610", + "size": 89211 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/files/delete", + "url": "https://platform.claude.com/docs/en/api/php/beta/models/retrieve", "status": "success", - "path": "en/api/terraform/beta/files/delete.md", - "sha256": "277ce0affe1e84fdb393bf7ff222dc6f7008ba14ff0f1d09067edd79ecd0000d", - "size": 91205 + "path": "en/api/php/beta/models/retrieve.md", + "sha256": "696231c9c9bb78a26a67295d019f36e3f83470559b0d10b86a3dd6e758110a15", + "size": 89223 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills", + "url": "https://platform.claude.com/docs/en/api/php/beta/messages", "status": "success", - "path": "en/api/terraform/beta/skills.md", - "sha256": "8f10b430f6bd7eb623fccd0142f0fc000cfee7a6f04f33504a0a6d3ae3f13fb1", - "size": 91183 + "path": "en/api/php/beta/messages.md", + "sha256": "28b092c1975376cdaf5a8317d223593f2d765df20d0e2723d7d96288d1f11184", + "size": 89198 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/messages/create", "status": "success", - "path": "en/api/terraform/beta/skills/create.md", - "sha256": "db3942313f6bf2665c43728a5d0a87a51dfe768c0fa12e807d0f285ef0983a7e", - "size": 91208 + "path": "en/api/php/beta/messages/create.md", + "sha256": "f5f00624e8dc6b6fc835d98aaa1d763403e1d9103fc6948d9bc0aaf500ffa281", + "size": 89223 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/list", + "url": "https://platform.claude.com/docs/en/api/php/beta/messages/count_tokens", "status": "success", - "path": "en/api/terraform/beta/skills/list.md", - "sha256": "4fac4877cd62db64ed841c2da11b559133e4d2aee6ed8611df647e957084fa0d", - "size": 91202 + "path": "en/api/php/beta/messages/count_tokens.md", + "sha256": "d4dd1262cbe24b55a60bd56457c75f23ffa228cc3015abe7421d94969d2f7fe8", + "size": 89241 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/retrieve", + "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches", "status": "success", - "path": "en/api/terraform/beta/skills/retrieve.md", - "sha256": "3b03fa7fd0164fb80b2478018d23f771c1b4e53244c299a00646f0653fd644ce", - "size": 91214 + "path": "en/api/php/beta/messages/batches.md", + "sha256": "629c4f7aefec50c22cd069c3d7d3126281ba049aa0c1ec5f1d4724048493b590", + "size": 89226 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/delete", + "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches/create", "status": "success", - "path": "en/api/terraform/beta/skills/delete.md", - "sha256": "f5332d7de31f376dd4135aa7b9c51fbc2b772638e426bd3e90a4260c9262d267", - "size": 91208 + "path": "en/api/php/beta/messages/batches/create.md", + "sha256": "16347ea093ac2d89a8cd10b1a7acba380cebb595d1b98533f8ba4bb7b6ec7a80", + "size": 89251 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/versions", + "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches/retrieve", "status": "success", - "path": "en/api/terraform/beta/skills/versions.md", - "sha256": "39f3636aa80f73a8abd1b35edfce2c507d2f116ac12afd0866638d5ef3146dfb", - "size": 91214 + "path": "en/api/php/beta/messages/batches/retrieve.md", + "sha256": "0c4b5b217826b5053ba3606e3a137cb5a20407725c12c35fee273c99906e29c4", + "size": 89257 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/versions/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches/list", "status": "success", - "path": "en/api/terraform/beta/skills/versions/create.md", - "sha256": "d1c9c848de2c65c6b0f652143e8a4aea686e77b8773dae7983cab0d66075fcfc", - "size": 91239 + "path": "en/api/php/beta/messages/batches/list.md", + "sha256": "94ca6eb4298d713f1fc2fffe37328d7be2ceb7bc3d92e6f06802f5a935cffadc", + "size": 89245 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/versions/list", + "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches/cancel", "status": "success", - "path": "en/api/terraform/beta/skills/versions/list.md", - "sha256": "780d0abdbc9550a822fbee056576abd4ae133f337bd480ccb0f083396d0b7863", - "size": 91233 + "path": "en/api/php/beta/messages/batches/cancel.md", + "sha256": "3acfea2e326b3827406a8263590ec2d1760971dcf6fae3f3cde32e539be1b6d6", + "size": 89251 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/versions/retrieve", + "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches/delete", "status": "success", - "path": "en/api/terraform/beta/skills/versions/retrieve.md", - "sha256": "354db4f17ab1aedc9cabe1421766746bbadc8e02a8015692199564cd2ed741f5", - "size": 91245 + "path": "en/api/php/beta/messages/batches/delete.md", + "sha256": "8943f0ad6f5735ee8d7a40540a6fa9b3dfde2eb22d1cdfb25a70cdd2723b39f2", + "size": 89251 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/skills/versions/delete", + "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches/results", "status": "success", - "path": "en/api/terraform/beta/skills/versions/delete.md", - "sha256": "b7798f49ba86dfad63e04085129ee7724be94da7d93d90d35c3f818a70cdbe34", - "size": 91239 + "path": "en/api/php/beta/messages/batches/results.md", + "sha256": "f7fc9c13fd9bc91f5ee7eb4aaf8ec7faeaac793e211f6d351840878833ae1c4a", + "size": 89254 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/user_profiles", + "url": "https://platform.claude.com/docs/en/api/php/beta/agents", "status": "success", - "path": "en/api/terraform/beta/user_profiles.md", - "sha256": "2da529334ce13ada8a384922c1a6eb25c75cfd9f3ed95add0635533760f35e5f", - "size": 91204 + "path": "en/api/php/beta/agents.md", + "sha256": "047fff9caffa938a1ce5e92cf5f5762ddca65238178b9f935ee25f7190bbf0be", + "size": 89192 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/user_profiles/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/agents/create", "status": "success", - "path": "en/api/terraform/beta/user_profiles/create.md", - "sha256": "1adc1ceac90ea6efedc53d277875dea46aa7bab7c72c9585f8171cc92e2f163c", - "size": 91229 + "path": "en/api/php/beta/agents/create.md", + "sha256": "313c8760d9f62b5d2a07927330024a4deb3e77e1996bb540204edf321243e2a3", + "size": 89217 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/user_profiles/list", + "url": "https://platform.claude.com/docs/en/api/php/beta/agents/list", "status": "success", - "path": "en/api/terraform/beta/user_profiles/list.md", - "sha256": "335e57b44d95fdb66ade559723c1500698157c17e63004f34e2e947c90ca07e8", - "size": 91223 + "path": "en/api/php/beta/agents/list.md", + "sha256": "4e81c5f29d1480ac4beac669e43b0a61fe1a1c147b0d7aff51cf33cc71df81f0", + "size": 89211 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/user_profiles/retrieve", + "url": "https://platform.claude.com/docs/en/api/php/beta/agents/retrieve", "status": "success", - "path": "en/api/terraform/beta/user_profiles/retrieve.md", - "sha256": "760c216c1c79abda66f24f1157f43166967557098b9a713e2c721c7167714521", - "size": 91235 + "path": "en/api/php/beta/agents/retrieve.md", + "sha256": "35e39bfe6c5b2361d38011a42e6cb15a4c4a3d8deb49fddb02792b78195bcc02", + "size": 89223 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/user_profiles/update", + "url": "https://platform.claude.com/docs/en/api/php/beta/agents/update", "status": "success", - "path": "en/api/terraform/beta/user_profiles/update.md", - "sha256": "134c2385b1da9135a1142beecfe863363a3abfccdd4aeb918742eb7016414102", - "size": 91229 + "path": "en/api/php/beta/agents/update.md", + "sha256": "1db76f3c3a7701b0605fa30a1ee9c6c58d3bce320b65c696c37cf1608d93de44", + "size": 89217 }, { - "url": "https://platform.claude.com/docs/en/api/terraform/beta/user_profiles/create_enrollment_url", + "url": "https://platform.claude.com/docs/en/api/php/beta/agents/archive", "status": "success", - "path": "en/api/terraform/beta/user_profiles/create_enrollment_url.md", - "sha256": "bca4d94675e3dd94f1783734ebebb9b66c6c16650b6d721afa941a747c30ccfc", - "size": 91274 + "path": "en/api/php/beta/agents/archive.md", + "sha256": "d7a46bf757b1b06fb9230a811399b158f22b850bec43d18cee8791fc040ebe4a", + "size": 89220 }, { - "url": "https://platform.claude.com/docs/en/api/cli/completions", + "url": "https://platform.claude.com/docs/en/api/php/beta/agents/versions", "status": "success", - "path": "en/api/cli/completions.md", - "sha256": "c8d0825b0bd07a08575248bba5568dfc624c657eaa531d87f27b54c5ab354933", - "size": 91161 + "path": "en/api/php/beta/agents/versions.md", + "sha256": "6088a5bcf34a7b6fc76330c81bfc92d4537f91c8088221180b748b4c37a85f3a", + "size": 89223 }, { - "url": "https://platform.claude.com/docs/en/api/cli/completions/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/agents/versions/list", "status": "success", - "path": "en/api/cli/completions/create.md", - "sha256": "7c42effbc990e1a7f3fc1a68e1c9af491642f741b84abd1d586e0fc1a923842d", - "size": 91186 + "path": "en/api/php/beta/agents/versions/list.md", + "sha256": "8ccfe554c30f38439ee0e200832233b858683b1223bdc43205ce54ae77b25f35", + "size": 89242 }, { - "url": "https://platform.claude.com/docs/en/api/cli/messages", + "url": "https://platform.claude.com/docs/en/api/php/beta/environments", "status": "success", - "path": "en/api/cli/messages.md", - "sha256": "e1ed202a207010b5e39376b4e3230ab8af873ea0e6601d70cdf2bddea55b60dd", - "size": 91152 + "path": "en/api/php/beta/environments.md", + "sha256": "29e67c3f3662b38e968fd70a16a8ccee0f7b3f142809e8c10f63c6bacdf3f538", + "size": 89210 }, { - "url": "https://platform.claude.com/docs/en/api/cli/messages/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/environments/create", "status": "success", - "path": "en/api/cli/messages/create.md", - "sha256": "fc8d57dcd0f61dcea55af0416555aa3eed0c0167cc34c9adbc86f8de6d33a1d2", - "size": 91177 + "path": "en/api/php/beta/environments/create.md", + "sha256": "c553da10ff414d362299c581360666dd9246444a0f89e750939f4855a22f66e8", + "size": 89235 }, { - "url": "https://platform.claude.com/docs/en/api/cli/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/php/beta/environments/list", "status": "success", - "path": "en/api/cli/messages/count_tokens.md", - "sha256": "df60b371353b3df5882ed7dbc3f6d7d38417ba66f654bbccdb6b79e108efac46", - "size": 91195 + "path": "en/api/php/beta/environments/list.md", + "sha256": "67e9b80bb62cfbf3b3931cd8b83cba72bb1741446ee5ec20521d7078abd03678", + "size": 89229 }, { - "url": "https://platform.claude.com/docs/en/api/cli/messages/batches", + "url": "https://platform.claude.com/docs/en/api/php/beta/environments/retrieve", "status": "success", - "path": "en/api/cli/messages/batches.md", - "sha256": "69450338a613357f840029bb5134be0ce58e981db41e115c543e972dac73db99", - "size": 91180 + "path": "en/api/php/beta/environments/retrieve.md", + "sha256": "1f2f76715913334698182796017184f56480566324c722fcf0c1ca37650108ef", + "size": 89241 }, { - "url": "https://platform.claude.com/docs/en/api/cli/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/environments/update", "status": "success", - "path": "en/api/cli/messages/batches/create.md", - "sha256": "89340efb5976e3e5245ef14aac70ae60ca7103eee48851136864f9dc6203c8ad", - "size": 91205 + "path": "en/api/php/beta/environments/update.md", + "sha256": "d088797d03a33a37556ec97af530a7eb362e433237ad7a32154ec32e5cb22426", + "size": 89235 }, { - "url": "https://platform.claude.com/docs/en/api/cli/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/php/beta/environments/delete", "status": "success", - "path": "en/api/cli/messages/batches/retrieve.md", - "sha256": "2e76f84474b7597cacfb5423bab568117967cd22fcc75ce3a06a7f95960ec927", - "size": 91211 + "path": "en/api/php/beta/environments/delete.md", + "sha256": "49e28391f6148c4e3adc4b9663246dff66c39a41a508f3114b4365a0fb6bbec4", + "size": 89235 }, { - "url": "https://platform.claude.com/docs/en/api/cli/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/php/beta/environments/archive", "status": "success", - "path": "en/api/cli/messages/batches/list.md", - "sha256": "178a758b95978d1a1d9e81d1244bbec03138a33c149eddce209166e3e7c0a7d0", - "size": 91199 + "path": "en/api/php/beta/environments/archive.md", + "sha256": "b0022e4a2942f58715a406bbc3160058969d4d8b5c2e34a21515e564974097a6", + "size": 89238 }, { - "url": "https://platform.claude.com/docs/en/api/cli/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions", "status": "success", - "path": "en/api/cli/messages/batches/cancel.md", - "sha256": "b168447f0e5acd273a7abb97bd98c4a2ea0f3d645a578a7f1eaf7b46dbd19c9f", - "size": 91205 + "path": "en/api/php/beta/sessions.md", + "sha256": "ac11ae2e07359a20db0bb244526d9538fc82d9c00dc1c751125185c193d51221", + "size": 89198 }, { - "url": "https://platform.claude.com/docs/en/api/cli/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/create", "status": "success", - "path": "en/api/cli/messages/batches/delete.md", - "sha256": "9440746b111a0fa527de711ba34b9d415ecba65e5458efffeb97ddd2f0704c2d", - "size": 91205 + "path": "en/api/php/beta/sessions/create.md", + "sha256": "a5323dfc0dd274879dca2d7caff134710f7c7495fe917aefed474ca864de75cb", + "size": 89223 }, { - "url": "https://platform.claude.com/docs/en/api/cli/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/list", "status": "success", - "path": "en/api/cli/messages/batches/results.md", - "sha256": "128c7a672ac52bd2c63d431391cc05e5d97c6bbf7fa54bf33a8c1ac718b3c958", - "size": 91208 + "path": "en/api/php/beta/sessions/list.md", + "sha256": "c991ae091204bb16e3769049ac8816dda9438642d2781141a94680a1d20b2216", + "size": 89217 }, { - "url": "https://platform.claude.com/docs/en/api/cli/models", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/retrieve", "status": "success", - "path": "en/api/cli/models.md", - "sha256": "3b2c6801c7979c37a89a67811782bee26f39747eae790e7f44ff368463098afa", - "size": 91146 + "path": "en/api/php/beta/sessions/retrieve.md", + "sha256": "d1563ae0af27d24721a86c1dd05f6218d3a007573b4184e9688af3415e92f7bf", + "size": 89229 }, { - "url": "https://platform.claude.com/docs/en/api/cli/models/list", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/update", "status": "success", - "path": "en/api/cli/models/list.md", - "sha256": "74d16546b94974a13e25824a69c40353d5c0e8521db27f0ece17606de4ed6264", - "size": 91165 + "path": "en/api/php/beta/sessions/update.md", + "sha256": "3a66baa761bd3f60035873c51d8bc4abfe78e5e7be77ec45f801f9d31e65c3c2", + "size": 89223 }, { - "url": "https://platform.claude.com/docs/en/api/cli/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/delete", "status": "success", - "path": "en/api/cli/models/retrieve.md", - "sha256": "8c8f6e17a302f16a9135fc49e1786a8a9febcd95d40ce151b4934e2aa8bcad83", - "size": 91177 + "path": "en/api/php/beta/sessions/delete.md", + "sha256": "cc68aa91428d9745528beaf92cd0e8c13b0d6b9109bcd0ea500c32a4a404755b", + "size": 89223 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/archive", "status": "success", - "path": "en/api/cli/beta.md", - "sha256": "115c7ae3fdc62876a7dc89e9b067f97964b96321c4f0c04abe363fda52a3f15e", - "size": 91140 + "path": "en/api/php/beta/sessions/archive.md", + "sha256": "4d9af57dd92def11adb0ddfdfe6cf3c960fdd7b1731d3c417e7f872460eeb9c3", + "size": 89226 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/models", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/events", "status": "success", - "path": "en/api/cli/beta/models.md", - "sha256": "7f05feb0987c08a9c1689ce5406afd670df0904eda5102b472f292510d7c8a95", - "size": 91165 + "path": "en/api/php/beta/sessions/events.md", + "sha256": "dfe604eb786f466602f25baec200c626499f9f39ca916b2b8e8a816caa6bfaa7", + "size": 89223 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/models/list", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/events/list", "status": "success", - "path": "en/api/cli/beta/models/list.md", - "sha256": "26cf5f3d92dc3f0c91988b49605faa95d241ebe7e30e73e5de4fe736bb61dba3", - "size": 91184 + "path": "en/api/php/beta/sessions/events/list.md", + "sha256": "deb1f41752aa76dbd7002d3110d05158b2998b0c4bf6db4c8b19042e21b23a88", + "size": 89242 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/events/send", "status": "success", - "path": "en/api/cli/beta/models/retrieve.md", - "sha256": "af220fd52b1fb2d01b052865e911bfdc49738a6ab1bb64cf7f4f62b3d291b8d6", - "size": 91196 + "path": "en/api/php/beta/sessions/events/send.md", + "sha256": "cba22b47bb5c13c1e0b981305405fe2763fc4452bb10778d661d6e0fe7052613", + "size": 89242 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/messages", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/events/stream", "status": "success", - "path": "en/api/cli/beta/messages.md", - "sha256": "8985d61e9fafca70e2e7b25ea4082d0da301e70d65c11991b4e82485de2f8fbc", - "size": 91171 + "path": "en/api/php/beta/sessions/events/stream.md", + "sha256": "14deb806b18217868db6dbc123ee0eb752d311cedf9875d8595709eb18faabde", + "size": 89248 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/resources", "status": "success", - "path": "en/api/cli/beta/messages/create.md", - "sha256": "f3f2632472289cd2cf687a8ab9dc0b56dedeabcfe1ccd5b6b2ea2149bc5abcb6", - "size": 91196 + "path": "en/api/php/beta/sessions/resources.md", + "sha256": "b376ab9f4aaf34aaa35cc1726665791e0b862564467a579da1d0a1e56691824a", + "size": 89232 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/resources/add", "status": "success", - "path": "en/api/cli/beta/messages/count_tokens.md", - "sha256": "389d16b6afe8222c903543c20367f371dfea0ec491ef15f6f7661caa043b7c26", - "size": 91214 + "path": "en/api/php/beta/sessions/resources/add.md", + "sha256": "be160b894f094239620bf2b6ca170dcf65f2b88a2a5f497c85d255246805c040", + "size": 89248 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/resources/list", "status": "success", - "path": "en/api/cli/beta/messages/batches.md", - "sha256": "24bdda7d15a3c3053b03a4f86e06d376cdaa3cdd897c1f84e24c20a1b76fc758", - "size": 91199 + "path": "en/api/php/beta/sessions/resources/list.md", + "sha256": "dd81c72ce9df7e0e03200cb394644eb849937e0331075e9f342d5260a896f72b", + "size": 89251 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/resources/retrieve", "status": "success", - "path": "en/api/cli/beta/messages/batches/create.md", - "sha256": "da54ddbb4e7ab2e0ebfec5d502eb8e044665e010f69d6bf4b0bc139d2e70019d", - "size": 91224 + "path": "en/api/php/beta/sessions/resources/retrieve.md", + "sha256": "8cfecca1c7b36f0714e2ec6f1d0b393a8a121dfe7b7bd43d62769b205be3806c", + "size": 89263 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/resources/update", "status": "success", - "path": "en/api/cli/beta/messages/batches/retrieve.md", - "sha256": "8f0c59778e09aec086f58cbfeb38dbcd1c0a6880b4c1ba718eae6282ff8046e1", - "size": 91230 + "path": "en/api/php/beta/sessions/resources/update.md", + "sha256": "cdcd95cc99ecc83610cacfc9b442b72af59af2c667d222cd76da614841c98474", + "size": 89257 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/php/beta/sessions/resources/delete", "status": "success", - "path": "en/api/cli/beta/messages/batches/list.md", - "sha256": "db288c7b8e8c622480d6f67c39d2a33a9a2444e077a8c28a453aeca2f6a2a573", - "size": 91218 + "path": "en/api/php/beta/sessions/resources/delete.md", + "sha256": "bb14179da6e60f7fd13b36f083910f4355b560bc9ccedb50cc6794ea514da768", + "size": 89257 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults", "status": "success", - "path": "en/api/cli/beta/messages/batches/cancel.md", - "sha256": "d3b5ca7c9f7b50ef665f2922924839cceae940eaeb5500d69093ccf0f3c0c409", - "size": 91224 + "path": "en/api/php/beta/vaults.md", + "sha256": "1d26ddeec5b6f88f582d7953857428a3129083da84ab947718b5f6042b7aea89", + "size": 89192 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/create", "status": "success", - "path": "en/api/cli/beta/messages/batches/delete.md", - "sha256": "c3c37601c563dc7b1962ce660fc857dedbe17f569d617bb530c4dcb04f192d27", - "size": 91224 + "path": "en/api/php/beta/vaults/create.md", + "sha256": "d56f8fae8599732cbb92336fa4d2fb984cea5e8f89e3c50e2d7231b143e54e3e", + "size": 89217 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/list", "status": "success", - "path": "en/api/cli/beta/messages/batches/results.md", - "sha256": "e75bb81785e43c132bf7b1d2c154504ec97a725f18ad9ab6e994b88d0446b7d4", - "size": 91227 + "path": "en/api/php/beta/vaults/list.md", + "sha256": "3f849e0d22bc7aacf9fd69b16434ae6afac1f6899cc15aa542045a2a98609ad8", + "size": 89211 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/files", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/retrieve", "status": "success", - "path": "en/api/cli/beta/files.md", - "sha256": "bb29b785076839f7e3ba3d2f6599e21dfc4eb2325173e7582f9ed4187367221e", - "size": 91162 + "path": "en/api/php/beta/vaults/retrieve.md", + "sha256": "9fd20faabc828f5ed96ae13de9164013f7a91ecc406baafa26058e47f05b8c02", + "size": 89223 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/files/upload", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/update", "status": "success", - "path": "en/api/cli/beta/files/upload.md", - "sha256": "7cb3010ed52652b645b1526f826c9664c889f13843f5a1b7fde1242e8c4ea995", - "size": 91187 + "path": "en/api/php/beta/vaults/update.md", + "sha256": "d3745a60160440abdd0f8ff9d0877c2c80a05756a0000b869253560e11d3071c", + "size": 89217 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/files/list", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/delete", "status": "success", - "path": "en/api/cli/beta/files/list.md", - "sha256": "cf7140d915c593444c32f8403579dbdf0bfd33a1eca65a3000bb2c5949be95b7", - "size": 91181 + "path": "en/api/php/beta/vaults/delete.md", + "sha256": "b7ba94068b92206ddf1b279043ce95cc83c2313d0c733713960d93046d4bfc7b", + "size": 89217 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/files/download", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/archive", "status": "success", - "path": "en/api/cli/beta/files/download.md", - "sha256": "ccaf4b59ee968f0468567947003b49206166a4415ca24287e07c33667b6b7d16", - "size": 91193 + "path": "en/api/php/beta/vaults/archive.md", + "sha256": "d661c6e4636c3a22314acdd113bd994e94f2735bcb20972cb452468820ba0da8", + "size": 89220 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/files/retrieve_metadata", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/credentials", "status": "success", - "path": "en/api/cli/beta/files/retrieve_metadata.md", - "sha256": "547bc03546010da113f0262215d852bfbe9817ac38621196515d0300d1af46ad", - "size": 91220 + "path": "en/api/php/beta/vaults/credentials.md", + "sha256": "8bb2b3c24261d3f08415bebc8a1740151c992ddf4862e841834aa625ff4c6c19", + "size": 89232 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/files/delete", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/credentials/create", "status": "success", - "path": "en/api/cli/beta/files/delete.md", - "sha256": "69afdeea5b6089f8e17b3f3672356f48bba9acb66b183374b23289eabf887d65", - "size": 91187 + "path": "en/api/php/beta/vaults/credentials/create.md", + "sha256": "32c95bedc1f13d5a68c669a3daee649ec8d80b4160aa8ada96375cd695ac8424", + "size": 89257 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/skills", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/credentials/list", "status": "success", - "path": "en/api/cli/beta/skills.md", - "sha256": "0db6e5cf8022bd4b23a9037d8b3ed195e474edb4496c705f80210f8a01b9cc28", - "size": 91165 + "path": "en/api/php/beta/vaults/credentials/list.md", + "sha256": "b871a2efaa70609bd044fe162c09f975855104c77b239c16ea9765e248062219", + "size": 89251 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/credentials/retrieve", "status": "success", - "path": "en/api/cli/beta/skills/create.md", - "sha256": "9e1619862e0c066f32744494cdc7f244156509b36d0df7f143af0514b020ffc7", - "size": 91190 + "path": "en/api/php/beta/vaults/credentials/retrieve.md", + "sha256": "67084611d2069ce1f2f61f458a98b07cdd39c400c3553be62bac8f7c3225b09f", + "size": 89263 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/list", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/credentials/update", "status": "success", - "path": "en/api/cli/beta/skills/list.md", - "sha256": "7e049ef345d832692b7bc0ab1125b47566f87fc30747f66d952141721bf345d8", - "size": 91184 + "path": "en/api/php/beta/vaults/credentials/update.md", + "sha256": "4bb512ee694d127f58c61f865703583665f9ec2dadc49e1ab5371e24491e94e6", + "size": 89257 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/retrieve", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/credentials/delete", "status": "success", - "path": "en/api/cli/beta/skills/retrieve.md", - "sha256": "40a156112035d70358463e36efe5422d220840c29108176099d3585014af5867", - "size": 91196 + "path": "en/api/php/beta/vaults/credentials/delete.md", + "sha256": "0188390f13d566d9d9647213fcd3d400886769e0d2a5daecc753ccd2b772ee52", + "size": 89257 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/delete", + "url": "https://platform.claude.com/docs/en/api/php/beta/vaults/credentials/archive", "status": "success", - "path": "en/api/cli/beta/skills/delete.md", - "sha256": "07572b8c2bbf34fbcc135d26b2050995951a0618a1c2e2711a5dafeaa4fde6e4", - "size": 91190 + "path": "en/api/php/beta/vaults/credentials/archive.md", + "sha256": "e930a30b586e8b91e717bf2022e8d9d1de37c69e67284d28ee256438788cb9c5", + "size": 89260 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/versions", + "url": "https://platform.claude.com/docs/en/api/php/beta/files", "status": "success", - "path": "en/api/cli/beta/skills/versions.md", - "sha256": "429ceb718d9db6b03c836e57ebdde5cec101fff4ef0344832757e4c2b1284dcb", - "size": 91196 + "path": "en/api/php/beta/files.md", + "sha256": "64b95bf48f33f260f145044c024b217704f97fca30e9b005d2aebc433fa24edc", + "size": 89189 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/versions/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/files/upload", "status": "success", - "path": "en/api/cli/beta/skills/versions/create.md", - "sha256": "68ec43bc39c3872c29c73fd9751c385a553bbbb02ee34ec48d3b5c135b7ecb72", - "size": 91221 + "path": "en/api/php/beta/files/upload.md", + "sha256": "f696e894243558185abc5a89c2c2cccb939e026835d22524cb1ab53855f1c94c", + "size": 89214 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/versions/list", + "url": "https://platform.claude.com/docs/en/api/php/beta/files/list", "status": "success", - "path": "en/api/cli/beta/skills/versions/list.md", - "sha256": "da8f4b2f5d7a41226b5db7088d85c481211129f2d12efae76f3da82fbf6005c3", - "size": 91215 + "path": "en/api/php/beta/files/list.md", + "sha256": "7bddd38cb03e5dbecfe53d8f12502a193bcc583bdd5fb35f2d10d783a5a61803", + "size": 89208 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/versions/retrieve", + "url": "https://platform.claude.com/docs/en/api/php/beta/files/download", "status": "success", - "path": "en/api/cli/beta/skills/versions/retrieve.md", - "sha256": "85349c21dd0734430e48e43ac5aa54db34ec4109feb294b0fa8f94e168492d73", - "size": 91227 + "path": "en/api/php/beta/files/download.md", + "sha256": "25b21363826fc26e7b57a49f35797eb330d5aa9eb4395c335a586b231ecbfa58", + "size": 89220 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/skills/versions/delete", + "url": "https://platform.claude.com/docs/en/api/php/beta/files/retrieve_metadata", "status": "success", - "path": "en/api/cli/beta/skills/versions/delete.md", - "sha256": "5a84553158683ba14c324f119979034736624135e3699223f65885587908a429", - "size": 91221 + "path": "en/api/php/beta/files/retrieve_metadata.md", + "sha256": "1e8b279aa5547efdb52aadc08bfbe3ffe058b2c2a82d52eaae50ef89e6218f83", + "size": 89247 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/user_profiles", + "url": "https://platform.claude.com/docs/en/api/php/beta/files/delete", "status": "success", - "path": "en/api/cli/beta/user_profiles.md", - "sha256": "8708690c4159aa07021ad6007146be19c7ede095477ada3f8da5e9056b02c6df", - "size": 91186 + "path": "en/api/php/beta/files/delete.md", + "sha256": "bf61bdb3798c99a75be42c0d999cb3f371196712457cc18fbeb7fdc02ba21fb1", + "size": 89214 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/user_profiles/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/skills", "status": "success", - "path": "en/api/cli/beta/user_profiles/create.md", - "sha256": "43ecba256a96b7f079441cd94fa223b8aa2866948b0340b98ba9b7a0ffb8be02", - "size": 91211 + "path": "en/api/php/beta/skills.md", + "sha256": "3548f860d98e11048696bab215530839d9af1c28bd2af1794634531bd418c86d", + "size": 89192 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/user_profiles/list", + "url": "https://platform.claude.com/docs/en/api/php/beta/skills/create", "status": "success", - "path": "en/api/cli/beta/user_profiles/list.md", - "sha256": "7a03c3595bab119d8b86ceb97cbbfb8896aabeb2df7e7f3bbcbc47fb53617d57", - "size": 91205 + "path": "en/api/php/beta/skills/create.md", + "sha256": "ab6dca9ce8511fbab511806a81053e3fbcbc00691f7ab905399fb48fe715e77b", + "size": 89217 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/user_profiles/retrieve", + "url": "https://platform.claude.com/docs/en/api/php/beta/skills/list", "status": "success", - "path": "en/api/cli/beta/user_profiles/retrieve.md", - "sha256": "29fb867b949e638f7aa6e5255a84d3fd4bbb0b82b59315fb3ad25d5703cf9453", - "size": 91217 + "path": "en/api/php/beta/skills/list.md", + "sha256": "8be4714b01503cba2ee6f75f686296e9deff19b4f3562fcb1bc6effcb0b17fe5", + "size": 89211 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/user_profiles/update", + "url": "https://platform.claude.com/docs/en/api/php/beta/skills/retrieve", "status": "success", - "path": "en/api/cli/beta/user_profiles/update.md", - "sha256": "5b2fda9f9153b3ebe3ce1820bc5d88eba29ba8127cd1176a64b9febd96d9dfdf", - "size": 91211 + "path": "en/api/php/beta/skills/retrieve.md", + "sha256": "ab404d04f6179f9e18fc15d509cfee747bb6bd6da42ca04d19f01b14643a6bfe", + "size": 89223 }, { - "url": "https://platform.claude.com/docs/en/api/cli/beta/user_profiles/create_enrollment_url", + "url": "https://platform.claude.com/docs/en/api/php/beta/skills/delete", "status": "success", - "path": "en/api/cli/beta/user_profiles/create_enrollment_url.md", - "sha256": "fc691039ae10d0a2bee01edc65b7c402314369f3b36bab54c22175d61e8dd6a3", - "size": 91256 + "path": "en/api/php/beta/skills/delete.md", + "sha256": "7d7fff9191b66a4d98da8a035fa61ec154be7a04fa26ffe3da5909811d596aa5", + "size": 89217 }, { - "url": "https://platform.claude.com/docs/en/api/php/completions", + "url": "https://platform.claude.com/docs/en/api/php/beta/skills/versions", "status": "success", - "path": "en/api/php/completions.md", - "sha256": "df97fed0b0c45534b2f9102c59aec226e501b6be48b54561c47346bc64b27581", - "size": 91161 + "path": "en/api/php/beta/skills/versions.md", + "sha256": "00d79130675cd34704616b51a1705a1b234b64c3e530e3f3c3e09902918fa184", + "size": 89223 }, { - "url": "https://platform.claude.com/docs/en/api/php/completions/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/skills/versions/create", "status": "success", - "path": "en/api/php/completions/create.md", - "sha256": "33ac77e98c6ed73b23dcbd309be168b0fd8266b905ed721457836a9f23b1c90f", - "size": 91186 + "path": "en/api/php/beta/skills/versions/create.md", + "sha256": "9ccfb3e2f759a9492c85fe56e4aa881040151e79fc256a2cd3f8d77d7bc1b282", + "size": 89248 }, { - "url": "https://platform.claude.com/docs/en/api/php/messages", + "url": "https://platform.claude.com/docs/en/api/php/beta/skills/versions/list", "status": "success", - "path": "en/api/php/messages.md", - "sha256": "511975f8f90ac285f06c1b0e71f62370e81b3c18a190485b80ce32c9ab7d9f78", - "size": 91152 + "path": "en/api/php/beta/skills/versions/list.md", + "sha256": "521f262f5ed57e03630076625f751d6215d5e4c9ed35cb619c7b0bb992d6187f", + "size": 89242 }, { - "url": "https://platform.claude.com/docs/en/api/php/messages/create", + "url": "https://platform.claude.com/docs/en/api/php/beta/skills/versions/retrieve", "status": "success", - "path": "en/api/php/messages/create.md", - "sha256": "e064df018b427fa0dd9df62fe5cc743b22ab09fde982abcb4b45382f93f1ae77", - "size": 91177 + "path": "en/api/php/beta/skills/versions/retrieve.md", + "sha256": "882fc5c38701493fa21b37de7c1f367a31941e7d6b451da62c2ed95aacb30b41", + "size": 89254 }, { - "url": "https://platform.claude.com/docs/en/api/php/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/php/beta/skills/versions/delete", "status": "success", - "path": "en/api/php/messages/count_tokens.md", - "sha256": "13ca11d9a5c6af5d344b4b4de79dd7682896439f46c4f0be70f4f1ae14fde5dd", - "size": 91195 + "path": "en/api/php/beta/skills/versions/delete.md", + "sha256": "3c627142637fa72cc7148a7a5de5fe2809b2ba102cc94b1291914318025806a4", + "size": 89248 }, { - "url": "https://platform.claude.com/docs/en/api/php/messages/batches", + "url": "https://platform.claude.com/docs/en/api/csharp/completions", "status": "success", - "path": "en/api/php/messages/batches.md", - "sha256": "0633d6b63ce45f35d64f00d3d22d413869f49067c849b2b27d016352a083eaf4", - "size": 91180 + "path": "en/api/csharp/completions.md", + "sha256": "1755d2314a2c83145e7bad5c3ab724254dbf1fe2b285e990a2b1487022ca30c2", + "size": 14 }, { - "url": "https://platform.claude.com/docs/en/api/php/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/csharp/completions/create", "status": "success", - "path": "en/api/php/messages/batches/create.md", - "sha256": "9f0af90b60d5b265bc64e4eb5c5bae4711f0571ee5360e0437054c0ebf7c4b1f", - "size": 91205 + "path": "en/api/csharp/completions/create.md", + "sha256": "8f22aefc25a57008dd7596f767b9cc5b4a7689a73ece6e88500d3cf65226b167", + "size": 55 }, { - "url": "https://platform.claude.com/docs/en/api/php/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/csharp/messages", "status": "success", - "path": "en/api/php/messages/batches/retrieve.md", - "sha256": "748492844892c433a6de5769837f6a670f24b2141df4b483f631e090d4fc28fb", - "size": 91211 + "path": "en/api/csharp/messages.md", + "sha256": "3eda67f4fbd65528cab2496246ee26621a545095d13d0636ecb220d5d3faa835", + "size": 816307 }, { - "url": "https://platform.claude.com/docs/en/api/php/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/csharp/messages/create", "status": "success", - "path": "en/api/php/messages/batches/list.md", - "sha256": "fad691848824f2a091b9201b06adbb45fc08c0fb2efb936f767903604189b7e5", - "size": 91199 + "path": "en/api/csharp/messages/create.md", + "sha256": "a0bb7598cbb69c399bfaf9621fa0411ea565ab7f3616c6993b784f620d3ad47d", + "size": 108702 }, { - "url": "https://platform.claude.com/docs/en/api/php/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/csharp/messages/count_tokens", "status": "success", - "path": "en/api/php/messages/batches/cancel.md", - "sha256": "8e5c4f8830c94a8d392d252ecc5d17f8d405449f2e57b34556a1d80ad809af67", - "size": 91205 + "path": "en/api/csharp/messages/count_tokens.md", + "sha256": "f735ced704b27a354349a1cdaab436b4a24aecf63ef65d3b1572dc63a9dcacac", + "size": 85357 }, { - "url": "https://platform.claude.com/docs/en/api/php/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches", "status": "success", - "path": "en/api/php/messages/batches/delete.md", - "sha256": "ac47313df81a3e2ac586c0ca3d99445a18cfc8221fb708d6f77ad312440814f7", - "size": 91205 + "path": "en/api/csharp/messages/batches.md", + "sha256": "a64debd7a740c1d1069ac6067e9f9a47bccd201259fccb7b715b6033fa114776", + "size": 225366 }, { - "url": "https://platform.claude.com/docs/en/api/php/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches/create", "status": "success", - "path": "en/api/php/messages/batches/results.md", - "sha256": "2a9676eb11a92ce6920890bdb98616a5511deafbdc04036fa75e7319cd682fd9", - "size": 91208 + "path": "en/api/csharp/messages/batches/create.md", + "sha256": "5707af633c1e75908891b0fc130f0f0554af947e158c6ef1d0ec33bb35bf6d16", + "size": 107748 }, { - "url": "https://platform.claude.com/docs/en/api/php/models", + "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches/retrieve", "status": "success", - "path": "en/api/php/models.md", - "sha256": "2faf0b400126f056ca8c22e46da09819585097e56b7a90161d7b26e10f6db547", - "size": 91146 + "path": "en/api/csharp/messages/batches/retrieve.md", + "sha256": "33403c909c4b95a8b56b758442a70d20ede48a00a669ac42134b0934e2589761", + "size": 3725 }, { - "url": "https://platform.claude.com/docs/en/api/php/models/list", + "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches/list", "status": "success", - "path": "en/api/php/models/list.md", - "sha256": "15db9b6be2cb984256d3217fa18be3e3e9c8d4f80fd6fad68b27caba66d0b133", - "size": 91165 + "path": "en/api/csharp/messages/batches/list.md", + "sha256": "bfba1ed1a3653d271e82086efc68a317c03a8e94200539974b3f3401235d8210", + "size": 4429 }, { - "url": "https://platform.claude.com/docs/en/api/php/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches/cancel", "status": "success", - "path": "en/api/php/models/retrieve.md", - "sha256": "c2c0b2a3ea57389869dcac7b4960e818d7454894896ef242569e8d3ec7f3e286", - "size": 91177 + "path": "en/api/csharp/messages/batches/cancel.md", + "sha256": "de247760e68f0309114ec1bf7b81b476ab47802e1589bca69675311dc5e6889d", + "size": 4031 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta", + "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches/delete", "status": "success", - "path": "en/api/php/beta.md", - "sha256": "2a7a9177d71f806a889544a44d5620b2096a54f91c11f31f3a3e5dbf1f2c5f31", - "size": 91140 + "path": "en/api/csharp/messages/batches/delete.md", + "sha256": "d4b8ec3c4191b872bf3534a181f1b5b2c2708cbd96934a05b9c0f2f69fb4d59d", + "size": 1077 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/models", + "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches/results", "status": "success", - "path": "en/api/php/beta/models.md", - "sha256": "ee2fed605dac6693decdc5cb7d9fa5dfdf369dea043cb970c756c7eed6cea9a8", - "size": 91165 + "path": "en/api/csharp/messages/batches/results.md", + "sha256": "b8d775128011b91c6588c8e4d7cc0f8a8ccd3e567d37696b7c5f5287c4da6466", + "size": 26725 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/models/list", + "url": "https://platform.claude.com/docs/en/api/csharp/models", "status": "success", - "path": "en/api/php/beta/models/list.md", - "sha256": "4940bb1b3fabe6840cab0ff0ee0c3baa3abea06992dc1a0f15af1bc933c468ec", - "size": 91184 + "path": "en/api/csharp/models.md", + "sha256": "ddbee4d7744df184243b7b3d7bd42c7c06262fd716804da1345bcacaadc1a4ed", + "size": 25572 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/csharp/models/list", "status": "success", - "path": "en/api/php/beta/models/retrieve.md", - "sha256": "f4b46ad21b939ea0a390b32ce888087effb968467fbee03fabc69fb3635bfc88", - "size": 91196 + "path": "en/api/csharp/models/list.md", + "sha256": "8ef50f30a282c287f643d837158efb3cc584c9624e657d402375022f1b915000", + "size": 7533 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/messages", + "url": "https://platform.claude.com/docs/en/api/csharp/models/retrieve", "status": "success", - "path": "en/api/php/beta/messages.md", - "sha256": "457003494209a066f57639cda69df910b9a1e8640c2b76886bcedeea7b9c7d18", - "size": 91171 + "path": "en/api/csharp/models/retrieve.md", + "sha256": "d66b6e9eb6fa3c7f35eef431ff3a7c567b0c72639470c6a1a5d8aee117b81917", + "size": 6536 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/messages/create", + "url": "https://platform.claude.com/docs/en/api/csharp/beta", "status": "success", - "path": "en/api/php/beta/messages/create.md", - "sha256": "6983cdc9990f60b39ba6cc8e6973eb5ecbc513316481f8d7889f95b0f1cf5a78", - "size": 91196 + "path": "en/api/csharp/beta.md", + "sha256": "35d9e1c417c10c9f5805404bcb3f1a2b5b1f8ef1d57c7648e94ec8d2cce347fe", + "size": 1617783 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/models", "status": "success", - "path": "en/api/php/beta/messages/count_tokens.md", - "sha256": "612089effb4667c37438eeb3170e9da405579b863e5983e9f10a2e85cb329942", - "size": 91214 + "path": "en/api/csharp/beta/models.md", + "sha256": "7ae78995f6d0475e59fd6080b2429348f708b46fce608e3c835361e45cfe292f", + "size": 26039 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/models/list", "status": "success", - "path": "en/api/php/beta/messages/batches.md", - "sha256": "a2a06b70cd7cb2817d1d50db4db44bc8c88086a801e1bfef8995225e4d1a15ac", - "size": 91199 + "path": "en/api/csharp/beta/models/list.md", + "sha256": "94abf704b8d0e06410611ba860ccea23dedcc8e203b6b6fc93762bfbe3983e83", + "size": 7627 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/models/retrieve", "status": "success", - "path": "en/api/php/beta/messages/batches/create.md", - "sha256": "84dbd30da69e2266d93b996124728a3ab6750d4203a2a644b9ea4e34137ae777", - "size": 91224 + "path": "en/api/csharp/beta/models/retrieve.md", + "sha256": "4180b260df9e0e19ddece9bf1cdf2bcac971688636d5b4c9616193ab5d608a55", + "size": 6642 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages", "status": "success", - "path": "en/api/php/beta/messages/batches/retrieve.md", - "sha256": "66fef54b33f32a0fb450e775103f267680e114cd838e48eddaf37835405c6357", - "size": 91230 + "path": "en/api/csharp/beta/messages.md", + "sha256": "6003b9c2b0f969c31728ca99cb7608ef1e6c5a14bbb97422e24091bcc433d312", + "size": 1006782 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/create", "status": "success", - "path": "en/api/php/beta/messages/batches/list.md", - "sha256": "a881a45bc87fb4b6813b704388940bb6e60066a28d49840360f21f06b1355eba", - "size": 91218 + "path": "en/api/csharp/beta/messages/create.md", + "sha256": "8d3f85f84ab9038aa35f4f87867e6ed7708ef9f65f8370c8095c916234d56bad", + "size": 135306 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/count_tokens", "status": "success", - "path": "en/api/php/beta/messages/batches/cancel.md", - "sha256": "03ec7283668f6a5ac936266cb2fe01bf05b7939941335c967531441d67a10777", - "size": 91224 + "path": "en/api/csharp/beta/messages/count_tokens.md", + "sha256": "9f37f843cbcacd38ea6c3c5f4f71116abce0feef34f0317120b2b28b051aef35", + "size": 103841 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches", "status": "success", - "path": "en/api/php/beta/messages/batches/delete.md", - "sha256": "fc78f7826b6c43f1c76d1d37fabe091543a7d4d06c7773fa3b53728d861e2eb8", - "size": 91224 + "path": "en/api/csharp/beta/messages/batches.md", + "sha256": "781b49d6c1e8b4bf3f5e3f5eca319017fb3c564af0d191899fe7fba12b2de379", + "size": 290606 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches/create", "status": "success", - "path": "en/api/php/beta/messages/batches/results.md", - "sha256": "e17bf53a3ca21b87aa8021966bdf993e1a671178366e90830d8db7dfe3bb30c3", - "size": 91227 + "path": "en/api/csharp/beta/messages/batches/create.md", + "sha256": "d53de96b19dba573be1a223064696088e771051b71efbf025600e8672d5ce9bb", + "size": 132562 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/files", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches/retrieve", "status": "success", - "path": "en/api/php/beta/files.md", - "sha256": "a28a8e47532cb1b5751fcfd36881b59580f115507dcaf3284636f1494b07c177", - "size": 91162 + "path": "en/api/csharp/beta/messages/batches/retrieve.md", + "sha256": "3e341f805e7fd59d7c0bcd5c911ea3509c39f69a44c36004309b98192adada4a", + "size": 5103 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/files/upload", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches/list", "status": "success", - "path": "en/api/php/beta/files/upload.md", - "sha256": "99dff7aa59b2827872515f4fcedb133af53e01bf30f690d174f29f0a9219efbb", - "size": 91187 + "path": "en/api/csharp/beta/messages/batches/list.md", + "sha256": "6d0d7a7f0772dc72f0a1cda128733b4e4d1ba757978960fe7afa04c1449412a8", + "size": 5848 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/files/list", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches/cancel", "status": "success", - "path": "en/api/php/beta/files/list.md", - "sha256": "cbd9d30b4c434c297c6f6ea09da02c0c77abd286b3de8e79c357b81951066a6b", - "size": 91181 + "path": "en/api/csharp/beta/messages/batches/cancel.md", + "sha256": "7732c21fbd74f058ffb6c4feabb94c708b4248fcdb1eb943d8ae8804d97e5c67", + "size": 5409 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/files/download", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches/delete", "status": "success", - "path": "en/api/php/beta/files/download.md", - "sha256": "4fba87f4dbed49202b43f193027e6275f5a4219a2ef5189e3c741f7906714cec", - "size": 91193 + "path": "en/api/csharp/beta/messages/batches/delete.md", + "sha256": "44490ac987b539a779d35f4b438b4bc0425daab6d2e6be1ccdfd2f26236c30da", + "size": 2451 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/files/retrieve_metadata", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches/results", "status": "success", - "path": "en/api/php/beta/files/retrieve_metadata.md", - "sha256": "7e25761039e5e9777d28309de843f1eb044356aee20bb32b0c94b07e9968d150", - "size": 91220 + "path": "en/api/csharp/beta/messages/batches/results.md", + "sha256": "d815e86f2c19a7d401fffdf4559d18a9d950c1e35b20d9822195e17e94885461", + "size": 36674 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/files/delete", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/agents", "status": "success", - "path": "en/api/php/beta/files/delete.md", - "sha256": "8aff1a5d6e0656a15e9b0b6addfc9a39240c0197fbb7d6dc165e5bc6f01cae83", - "size": 91187 + "path": "en/api/csharp/beta/agents.md", + "sha256": "a70cb62e9949e7ec41a0c84d3a61074bf29a856c5a349e947dcaa4d01a4c4787", + "size": 102196 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/skills", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/agents/create", "status": "success", - "path": "en/api/php/beta/skills.md", - "sha256": "4e547af445f489f6f980bf934ac025d88d066b1e7131efb47b0f14751a1684a6", - "size": 91165 + "path": "en/api/csharp/beta/agents/create.md", + "sha256": "74ebd5cd49e1976c8e992cc797e9b10c0bf2b057eef3689e9e92b17d6d1e6c24", + "size": 18530 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/skills/create", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/agents/list", "status": "success", - "path": "en/api/php/beta/skills/create.md", - "sha256": "905792a68e8ea49789b13735fa28f03971a9eb501b55752a18206bc1471abb21", - "size": 91190 + "path": "en/api/csharp/beta/agents/list.md", + "sha256": "aae243c18ea78d864de5f6d5b39105ccef7fa7f52b724fa5fcc7de144b309102", + "size": 9519 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/skills/list", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/agents/retrieve", "status": "success", - "path": "en/api/php/beta/skills/list.md", - "sha256": "5d4441dc80d30778f8873ecf209404e71910d5c3af41b1bee2c21a5f7ae34268", - "size": 91184 + "path": "en/api/csharp/beta/agents/retrieve.md", + "sha256": "84abd8d8aa413087b35c7ac3a152b0b86a1555c4688223c6f95a614c80b40ece", + "size": 8837 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/skills/retrieve", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/agents/update", "status": "success", - "path": "en/api/php/beta/skills/retrieve.md", - "sha256": "03bd7e36e16776090acea4fdb865c5b7224cc57f7a3c324fe7825b2e8936fa64", - "size": 91196 + "path": "en/api/csharp/beta/agents/update.md", + "sha256": "fb17263624686afe71bc6a07db855be8e74b2ff1ed249defb861dc7f4d02158b", + "size": 19203 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/skills/delete", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/agents/archive", "status": "success", - "path": "en/api/php/beta/skills/delete.md", - "sha256": "bbe5f2b103a8abee4e5c20535d90ee7e784337a4d7b29d82fbb4807145fb24c6", - "size": 91190 + "path": "en/api/csharp/beta/agents/archive.md", + "sha256": "2009dc8cdf7fc455af0af1aab47b6046e4493fcde132e4572a0dcf4cf976fec0", + "size": 8699 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/skills/versions", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/agents/versions", "status": "success", - "path": "en/api/php/beta/skills/versions.md", - "sha256": "93e209997870345e2aa7eee40b46c27bdb27ae19d90d5718f53e29a3cefaa152", - "size": 91196 + "path": "en/api/csharp/beta/agents/versions.md", + "sha256": "37bfbb21ddeb61591fa2268744dd02a26401a3e5b191dba65f25a82637abaa33", + "size": 9367 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/skills/versions/create", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/agents/versions/list", "status": "success", - "path": "en/api/php/beta/skills/versions/create.md", - "sha256": "a1218fdf8cbf43ce40016f12d2d7537ce0f1b3a2584bb4298a0c664cdd7ab9a5", - "size": 91221 + "path": "en/api/csharp/beta/agents/versions/list.md", + "sha256": "901d41cd3c28d6aa3608b51d566143d58a2d54644e9edc8716d9b48c7a0281e9", + "size": 9355 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/skills/versions/list", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/environments", "status": "success", - "path": "en/api/php/beta/skills/versions/list.md", - "sha256": "3ae450f08f6c9b63f207b9f673ad600d9f2145e0ffb74bc01c5ec7b347db487b", - "size": 91215 + "path": "en/api/csharp/beta/environments.md", + "sha256": "484b348d3cde7fadccc9b8b3dc4ea7770bcc70f4b21b087e16ccb485556cf3fb", + "size": 35480 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/skills/versions/retrieve", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/environments/create", "status": "success", - "path": "en/api/php/beta/skills/versions/retrieve.md", - "sha256": "aaec3c2ea39e410a8dd5e43ddd9137ec3d907d3d719454a50b06a602ce980670", - "size": 91227 + "path": "en/api/csharp/beta/environments/create.md", + "sha256": "093c99b9a7bc97ac38a7992d39c065a7d30e1857fc86f6d482e3a8eb53c7cbba", + "size": 4832 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/skills/versions/delete", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/environments/list", "status": "success", - "path": "en/api/php/beta/skills/versions/delete.md", - "sha256": "d9e982919a294a37c065f305ffa3d6c0b7ae48ba42fe348e0539e74c8ff2c42a", - "size": 91221 + "path": "en/api/csharp/beta/environments/list.md", + "sha256": "6d5d29748f8c9b7c9fededb812c4b9af6cdfa0d67b701cb29410436acbe8b5dc", + "size": 5163 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/user_profiles", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/environments/retrieve", "status": "success", - "path": "en/api/php/beta/user_profiles.md", - "sha256": "564686b9d82f3116fffb6d007478a76a68eae6494994a57cc063329bcedf0a73", - "size": 91186 + "path": "en/api/csharp/beta/environments/retrieve.md", + "sha256": "11d39bb148ae1f4f50791fd689d9905bf2816c343622b111f5348b6c0712a30c", + "size": 4411 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/user_profiles/create", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/environments/update", "status": "success", - "path": "en/api/php/beta/user_profiles/create.md", - "sha256": "521536d848fceca52e4f91290e05a9256b9fc6333f44c0fef8a48ff27b69b3a1", - "size": 91211 + "path": "en/api/csharp/beta/environments/update.md", + "sha256": "2b37e9bd4cefbb606d7807a02e4a01a8ff5852144252b258c3636427715be284", + "size": 4952 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/user_profiles/list", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/environments/delete", "status": "success", - "path": "en/api/php/beta/user_profiles/list.md", - "sha256": "7311558074872dd6e241bab998cc012dd47b1f64d971daaffd2f6bd817b28ac5", - "size": 91205 + "path": "en/api/csharp/beta/environments/delete.md", + "sha256": "f1b5c3adfa7b90e18b8474b13a1ff261782a05c35f72d2014480ead5ce2a8205", + "size": 2206 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/user_profiles/retrieve", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/environments/archive", "status": "success", - "path": "en/api/php/beta/user_profiles/retrieve.md", - "sha256": "254f694162a7f7605c9ea9a7e3590afbeb0e20c02f2cb141d0fee3f63fa1abc9", - "size": 91217 + "path": "en/api/csharp/beta/environments/archive.md", + "sha256": "c7c991fa0362f70b53352de7d1f5bf295187e5a678fb5d4319cf72f026291232", + "size": 4466 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/user_profiles/update", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions", "status": "success", - "path": "en/api/php/beta/user_profiles/update.md", - "sha256": "95834e8d6d153702e86e1b88316885c6a8b78f7f51f3e92874f2dc0a7148e540", - "size": 91211 + "path": "en/api/csharp/beta/sessions.md", + "sha256": "3b41084193d92bd208e49b098e5eeb4b46419fc45ab243f606e06da25ee67b11", + "size": 341141 }, { - "url": "https://platform.claude.com/docs/en/api/php/beta/user_profiles/create_enrollment_url", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/create", "status": "success", - "path": "en/api/php/beta/user_profiles/create_enrollment_url.md", - "sha256": "2efb1bba72f9747a8aa158d94e18d8184c8537118079227090537439f5e73301", - "size": 91256 + "path": "en/api/csharp/beta/sessions/create.md", + "sha256": "7da8988b2758d3ead4c8b9f024f60e900a45935cc2ec57178abe7004287247bf", + "size": 14365 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/completions", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/list", "status": "success", - "path": "en/api/csharp/completions.md", - "sha256": "1755d2314a2c83145e7bad5c3ab724254dbf1fe2b285e990a2b1487022ca30c2", - "size": 14 + "path": "en/api/csharp/beta/sessions/list.md", + "sha256": "2f577873955f8e1a11c38f1aae17c1879a8be4aac3b035dc1cec5cf64ca36135", + "size": 13342 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/completions/create", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/retrieve", "status": "success", - "path": "en/api/csharp/completions/create.md", - "sha256": "8f22aefc25a57008dd7596f767b9cc5b4a7689a73ece6e88500d3cf65226b167", - "size": 55 + "path": "en/api/csharp/beta/sessions/retrieve.md", + "sha256": "923ef9e1ac91caf78b409c96e431ef2b1060fb3f59f627a6346b1688d8032448", + "size": 11808 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/messages", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/update", "status": "success", - "path": "en/api/csharp/messages.md", - "sha256": "474cb961c0b20f9623842001640399f7d4449e0cde1a72e8becaa1e38c9ddbd9", - "size": 815102 + "path": "en/api/csharp/beta/sessions/update.md", + "sha256": "4c270c11d305175b055da01d8041cb4e5eae41fc0a148c3f1c24f206256b34db", + "size": 12256 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/messages/create", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/delete", "status": "success", - "path": "en/api/csharp/messages/create.md", - "sha256": "7cd054dc7608f748a94aa1079cc3d712f2d4ebfb5833ee361ed29aed7a554ec8", - "size": 108575 + "path": "en/api/csharp/beta/sessions/delete.md", + "sha256": "86bf63d092e825b80b6250bac1623a01110a11d3f2b962042bbb19520d90145e", + "size": 2135 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/archive", "status": "success", - "path": "en/api/csharp/messages/count_tokens.md", - "sha256": "56d13c5beaa50bd7f37e5149410f1a69b715672217d0c7bc3873cdebf2c40310", - "size": 85351 + "path": "en/api/csharp/beta/sessions/archive.md", + "sha256": "e4e821d91cfa6819a341a1ddc8b0c69b8f097d5070b07922c654271825a75714", + "size": 11815 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/events", "status": "success", - "path": "en/api/csharp/messages/batches.md", - "sha256": "d858129969cf0e93c6b4274fa652005b2351872b7e0441eb0ace1586ae1c9f2f", - "size": 224687 + "path": "en/api/csharp/beta/sessions/events.md", + "sha256": "bf3c1e17695f46819ce16a253b7097d28a7c8af6f7ed016318344e8d4278b165", + "size": 236789 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/events/list", "status": "success", - "path": "en/api/csharp/messages/batches/create.md", - "sha256": "3205ba87b32def4d05c65e413c2345d22405fa616f93b07a2b8a023a514189d9", - "size": 107613 + "path": "en/api/csharp/beta/sessions/events/list.md", + "sha256": "e40304c178a4d29695773c129deacf7137044c3675a8b91a4a1177d90f6962c8", + "size": 37682 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/events/send", "status": "success", - "path": "en/api/csharp/messages/batches/retrieve.md", - "sha256": "33403c909c4b95a8b56b758442a70d20ede48a00a669ac42134b0934e2589761", - "size": 3725 + "path": "en/api/csharp/beta/sessions/events/send.md", + "sha256": "907cd8e51ca9a90e4939fb6ea09ed3b98f93a96e097c98dbd1995f7c9669d89c", + "size": 20290 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/events/stream", "status": "success", - "path": "en/api/csharp/messages/batches/list.md", - "sha256": "bfba1ed1a3653d271e82086efc68a317c03a8e94200539974b3f3401235d8210", - "size": 4429 + "path": "en/api/csharp/beta/sessions/events/stream.md", + "sha256": "1674ef6fff9c59557641e9971052842b6872b4953b1909efdfc468f9815645e8", + "size": 35920 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/resources", "status": "success", - "path": "en/api/csharp/messages/batches/cancel.md", - "sha256": "de247760e68f0309114ec1bf7b81b476ab47802e1589bca69675311dc5e6889d", - "size": 4031 + "path": "en/api/csharp/beta/sessions/resources.md", + "sha256": "5a384619fbe07edc9dd7c034ab2d1040d43151a6008409cd384e216f2e14e8a9", + "size": 18331 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/resources/add", "status": "success", - "path": "en/api/csharp/messages/batches/delete.md", - "sha256": "d4b8ec3c4191b872bf3534a181f1b5b2c2708cbd96934a05b9c0f2f69fb4d59d", - "size": 1077 + "path": "en/api/csharp/beta/sessions/resources/add.md", + "sha256": "aafea55154b328273610e63768f00595e0fd985c304a79426d1c8068ddbf389a", + "size": 2634 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/resources/list", "status": "success", - "path": "en/api/csharp/messages/batches/results.md", - "sha256": "8bea0c495de570d8ea7c84881c5b73192958c471d96c7c28becf4429140c39e6", - "size": 26586 + "path": "en/api/csharp/beta/sessions/resources/list.md", + "sha256": "4e96c1ab521871c3327fefc20a7f12bb02b26338ea53167e172ac6780386cc65", + "size": 3702 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/models", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/resources/retrieve", "status": "success", - "path": "en/api/csharp/models.md", - "sha256": "8aa979c54b70f3f42d9e28d7cd952c22ea5930f6e0265672a59365cca8abd3a3", - "size": 25688 + "path": "en/api/csharp/beta/sessions/resources/retrieve.md", + "sha256": "200f57b30bb7e2b45474c94c3154f6370d4de7e25d64635255e82477f9ac8c62", + "size": 3356 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/models/list", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/resources/update", "status": "success", - "path": "en/api/csharp/models/list.md", - "sha256": "9f65afaf49bb102609a125b667c16d8d2527b721695e8b66632c412b2170f0e7", - "size": 7591 + "path": "en/api/csharp/beta/sessions/resources/update.md", + "sha256": "23a2b249288c360cefd680f0c59007a52682414d6649ad05212a67222a31efb6", + "size": 3557 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/sessions/resources/delete", "status": "success", - "path": "en/api/csharp/models/retrieve.md", - "sha256": "96f8b613464e22c24acf1faac852cce1da5859c9f1332cce71cc343be390b6ae", - "size": 6594 + "path": "en/api/csharp/beta/sessions/resources/delete.md", + "sha256": "15be1918ded1ed9001fe07fa6a4c017e7e575ca6c162de7163b3030719ae6734", + "size": 2368 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults", "status": "success", - "path": "en/api/csharp/beta.md", - "sha256": "43b12a9d30a6c26db2af11902d85049516fb44e2ae347846edc1840f6c2d8888", - "size": 1087810 + "path": "en/api/csharp/beta/vaults.md", + "sha256": "23cb1d3ec0c262a13c50e4129182ffaa115dda7e2143c9171d7cdef1ee7f05b6", + "size": 63450 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/models", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/create", "status": "success", - "path": "en/api/csharp/beta/models.md", - "sha256": "a368432005773f88d37046a62762c380af551f49c3d287b81a8621d9d744d44b", - "size": 26155 + "path": "en/api/csharp/beta/vaults/create.md", + "sha256": "8674c65ea504ab2bae94375b27b5ac263dba6ac9f90ca33f5b3a1b4379ae8bcc", + "size": 2681 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/models/list", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/list", "status": "success", - "path": "en/api/csharp/beta/models/list.md", - "sha256": "09adf26a995207dd6899bf6f15e5b8f2817277a8351bb0f7fec436daf222ee70", - "size": 7685 + "path": "en/api/csharp/beta/vaults/list.md", + "sha256": "81bc4a87a480c82f8cedb88abad20d66ec6cc54d0bbb1de1a443575ea6c944fa", + "size": 2903 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/models/retrieve", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/retrieve", "status": "success", - "path": "en/api/csharp/beta/models/retrieve.md", - "sha256": "9761e33b9ea22a7a951531e750e541646dc22594d1acb975ea5950969e1e8d1c", - "size": 6700 + "path": "en/api/csharp/beta/vaults/retrieve.md", + "sha256": "d2a6e3193cc741e4dbb02777d8c2a5b8b894c19e0b807dbbc78c2dad13370938", + "size": 2534 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/update", "status": "success", - "path": "en/api/csharp/beta/messages.md", - "sha256": "84d9ec776cd0d4354fa9e042fa09f85960ddc5551da5c8e22c48a0b69c6690e8", - "size": 1006414 + "path": "en/api/csharp/beta/vaults/update.md", + "sha256": "4aad29ff944cb8ddce08d540a6db872cdb03f235f7ff0dc2ada7d7e59c612429", + "size": 2832 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/create", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/delete", "status": "success", - "path": "en/api/csharp/beta/messages/create.md", - "sha256": "16a13400f4a02ac3547f0e33e4a5ed5f27f35f11d21b99e23da4ab96243ec722", - "size": 135400 + "path": "en/api/csharp/beta/vaults/delete.md", + "sha256": "b6a6cd5957a161213173a7bca942b32655d633505ccb5f36d8fff54c696f4211", + "size": 2118 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/count_tokens", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/archive", "status": "success", - "path": "en/api/csharp/beta/messages/count_tokens.md", - "sha256": "17873469efc1b5e51993d47aafe07b4167b809701f6f1d23b7f64bd99b6aef4e", - "size": 103893 + "path": "en/api/csharp/beta/vaults/archive.md", + "sha256": "b3d24905af7a6772683ec793745f7394cdcb58f2c7c2462af5d27427955b0e69", + "size": 2541 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/credentials", "status": "success", - "path": "en/api/csharp/beta/messages/batches.md", - "sha256": "a87b4110e203a3258454d688be3d9b2a2c740fa9be4e24f672aec75eac6974cc", - "size": 290485 + "path": "en/api/csharp/beta/vaults/credentials.md", + "sha256": "eba994b0ec5166901ff85e4031a0ab9220c19459a0c8c94af9ff7e7ba250ff30", + "size": 46883 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches/create", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/credentials/create", "status": "success", - "path": "en/api/csharp/beta/messages/batches/create.md", - "sha256": "820f03bfb2c8cf0f7413c1350918a5fc031826a61616d2ad7c48939304f4149f", - "size": 132695 + "path": "en/api/csharp/beta/vaults/credentials/create.md", + "sha256": "a45225a0f9f67e66068f9fd36eeb4ef918ee8df9ef3e54cc3b8634b33a840ae7", + "size": 7602 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches/retrieve", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/credentials/list", "status": "success", - "path": "en/api/csharp/beta/messages/batches/retrieve.md", - "sha256": "85ecd99515bd6b8dbed589d97b968c3e7b630f4859e49c666864c4050b5fca9f", - "size": 5161 + "path": "en/api/csharp/beta/vaults/credentials/list.md", + "sha256": "b6fe3e87714a7cd1bf6e3b67b58becab9491a9b0c60ffdc9dc4372fa7f8cdf48", + "size": 5323 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches/list", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/credentials/retrieve", "status": "success", - "path": "en/api/csharp/beta/messages/batches/list.md", - "sha256": "046ab85f7d76b416a7d8695fa7c4bafdb474a800186d5f5d7bac306ada10f405", - "size": 5906 + "path": "en/api/csharp/beta/vaults/credentials/retrieve.md", + "sha256": "3783f8b85f16d8dc7cb83d81e221756bae35f31e96e686a6e100095a3db9b18d", + "size": 4911 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches/cancel", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/credentials/update", "status": "success", - "path": "en/api/csharp/beta/messages/batches/cancel.md", - "sha256": "4bca1f8a36ed5948078524d9bd86ae0a6028d3b380ce51718c2821ba8d7b436a", - "size": 5467 + "path": "en/api/csharp/beta/vaults/credentials/update.md", + "sha256": "a0f8d24e8096c3118269eb56804725608d310140c0318dbd86793225ce808794", + "size": 6999 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches/delete", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/credentials/delete", "status": "success", - "path": "en/api/csharp/beta/messages/batches/delete.md", - "sha256": "c0dc7724f62d1845aa08660dca15383bcbc0cfbdcf730c0dafd70fa57d81dfa9", - "size": 2509 + "path": "en/api/csharp/beta/vaults/credentials/delete.md", + "sha256": "207c03f4fb490f668bee0b7dbdb22bc72b46d31d74828276ce4c8e8aadae8be6", + "size": 2402 }, { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/messages/batches/results", + "url": "https://platform.claude.com/docs/en/api/csharp/beta/vaults/credentials/archive", "status": "success", - "path": "en/api/csharp/beta/messages/batches/results.md", - "sha256": "0f4074b8d782af5be1b5c2a653fabe38fdbd00e01469d1f14a6561430a5d3a20", - "size": 36593 + "path": "en/api/csharp/beta/vaults/credentials/archive.md", + "sha256": "dd7947fea067b74dec29421ccd354af7f6bc46edff969faa91fa04acdaa759c7", + "size": 4918 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/files", "status": "success", "path": "en/api/csharp/beta/files.md", - "sha256": "05aafb6177333279ce32d8d84b7d224f05a53ee08fa48cc0fcf93076e42b989b", - "size": 13169 + "sha256": "e70a0f1769283f975012fb03866eec70b2f1c9987405033dca67be661fc88cc4", + "size": 14459 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/files/upload", "status": "success", "path": "en/api/csharp/beta/files/upload.md", - "sha256": "3d54d6fa3e86565ed338c5619bbfad31c0d017fd6075baf397a4c762edd9a77d", - "size": 2532 + "sha256": "3035c57924bd8689f299ea8da74a39e00369d0022177fb86612aa017cc2d78ac", + "size": 2777 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/files/list", "status": "success", "path": "en/api/csharp/beta/files/list.md", - "sha256": "689751458ecc43515da14f80a29ebaeb4755bf54b7e02e6c1f91975a850adef0", - "size": 3241 + "sha256": "fa8b3cff6a0d35b630a4b550a6bd16ff1b3f64adc0bc1052e65d1bf1d20c7d39", + "size": 3635 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/files/download", "status": "success", "path": "en/api/csharp/beta/files/download.md", - "sha256": "bfbe6336a3835b971dc0d91fa3bcf65eca9c46df9e4a586847f6c5ccdfa8e6af", - "size": 1868 + "sha256": "bd6bc796c7656bb0c3cafc00c9cb615469043c9bc8c501c13d7c00fc0da20a7e", + "size": 1810 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/files/retrieve_metadata", "status": "success", "path": "en/api/csharp/beta/files/retrieve_metadata.md", - "sha256": "20ba7ae753a68d3e63a9491326894293a88093d21534fa5b6e0b006c7aa52640", - "size": 2550 + "sha256": "90965758841e69edf5d383fc37dc51db35d3203039e17674ca9cda4a7bef0a95", + "size": 2795 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/files/delete", "status": "success", "path": "en/api/csharp/beta/files/delete.md", - "sha256": "cb85cf7451f1b21b7dfaa6ec661a733118a033de2e38c014e6aead45ec7fec55", - "size": 2081 + "sha256": "21430b2118ca3651ea249205a6af4030d37ed23f6543f117ad54248f24805514", + "size": 2023 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/skills", "status": "success", "path": "en/api/csharp/beta/skills.md", - "sha256": "32613d07137229cf038d1760256eb1683796f351e56c2b759cca6ff0becdbbe4", - "size": 24951 + "sha256": "8c7f2d9a799551c87ccf927baeb3fc7150f3314c943edfb381273703c8b57367", + "size": 24487 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/skills/create", "status": "success", "path": "en/api/csharp/beta/skills/create.md", - "sha256": "8572536b9983748d12dd0102f7964e6001f7b2815b6066b90a443f72dc292b00", - "size": 3127 + "sha256": "5da3519b9a13ac11858c8aa27273467ea913a3ba0ada02a81de50f65268cb59b", + "size": 3069 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/skills/list", "status": "success", "path": "en/api/csharp/beta/skills/list.md", - "sha256": "a329a4245fba162aaee2f390a1de6c8592d30d34b03d97e0f17ea3fd4a33eaad", - "size": 3872 + "sha256": "8a85f5bb82f36f6110c14a7280db9224b55a9707e14314dc03f9feea0019700e", + "size": 3814 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/skills/retrieve", "status": "success", "path": "en/api/csharp/beta/skills/retrieve.md", - "sha256": "71a4361189bcc8504b414505aabd8c579ac08ee25acf0a9224b0eaabf74ed028", - "size": 2918 + "sha256": "39d67d39531438085c2196c0a649db32e5c0cf09498a1b06e0b31bb2d1d68170", + "size": 2860 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/skills/delete", "status": "success", "path": "en/api/csharp/beta/skills/delete.md", - "sha256": "efc4412139778e69fde63929953cfc3f0694d290074541c242fac94cf4c8e8af", - "size": 2204 + "sha256": "f52f2651ddd90c95cba488036e46d4a03c8038bd57c8f2de59034a0856678f1f", + "size": 2146 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/skills/versions", "status": "success", "path": "en/api/csharp/beta/skills/versions.md", - "sha256": "c26f396ae8b12082ec1c4f0410b7d115f5d8d45c5cbbe5884422485f484781b8", - "size": 12816 + "sha256": "a334e86ccd2a937b5819fcdea787453cb3b7bea91390a5b78679b748e3892bac", + "size": 12584 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/skills/versions/create", "status": "success", "path": "en/api/csharp/beta/skills/versions/create.md", - "sha256": "9b618f96a3b4c3eb6b0e8b89e6507b2b254c4cbb20c9129ae27669c748b6d57d", - "size": 3275 + "sha256": "7d5eef0c6e884bfb9f0e03b118d7b1ea790e65721a684a7dff06023d2068658d", + "size": 3217 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/skills/versions/list", "status": "success", "path": "en/api/csharp/beta/skills/versions/list.md", - "sha256": "b4280740d1810b8fed0b56ac0519e423c7e9af20dbca41111b47478caf5eed5b", - "size": 3700 + "sha256": "44c0af4c8fb7a6ef8550f84b98bfb749462b73dc18d3db1cd62acd98a251fdfd", + "size": 3642 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/skills/versions/retrieve", "status": "success", "path": "en/api/csharp/beta/skills/versions/retrieve.md", - "sha256": "c05655ef2d7c1effbfccc354cc6ba9e50867663318d947d19962ca2e15dc5b47", - "size": 3292 + "sha256": "03380734193c4b21a065ec19c4e47cc4740a513a246a4ddac76b8fcc023b6f6c", + "size": 3234 }, { "url": "https://platform.claude.com/docs/en/api/csharp/beta/skills/versions/delete", "status": "success", "path": "en/api/csharp/beta/skills/versions/delete.md", - "sha256": "71c52bbc8a11e7577cec64d95823a4a7052038662e541aaad8da038ed59a73fd", - "size": 2534 - }, - { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/user_profiles", - "status": "success", - "path": "en/api/csharp/beta/user_profiles.md", - "sha256": "72dacb634f3e0044ea3a93d66a3a1e2ab9904823d165be3d18d44b6025cdd3c7", - "size": 13375 - }, - { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/user_profiles/create", - "status": "success", - "path": "en/api/csharp/beta/user_profiles/create.md", - "sha256": "c6dbeff57b6d7548e3ba88b8593ed6093afc7066dca2dabff1aed1e1df22d3ec", - "size": 2579 - }, - { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/user_profiles/list", - "status": "success", - "path": "en/api/csharp/beta/user_profiles/list.md", - "sha256": "2ddef90904f6cacc8f3ea146e85502fc1c9b34f3c7da639038978480db70d515", - "size": 2656 - }, - { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/user_profiles/retrieve", - "status": "success", - "path": "en/api/csharp/beta/user_profiles/retrieve.md", - "sha256": "5d8c226a262846f84e136bb13b2ec90128e05dc5ba1abe13b15891617e2d7b8b", - "size": 2358 - }, - { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/user_profiles/update", - "status": "success", - "path": "en/api/csharp/beta/user_profiles/update.md", - "sha256": "ed78d701de73b5f7559d2e2ca8d3392d294b38cb535fd9c1b507f055d25f0a06", - "size": 2748 - }, - { - "url": "https://platform.claude.com/docs/en/api/csharp/beta/user_profiles/create_enrollment_url", - "status": "success", - "path": "en/api/csharp/beta/user_profiles/create_enrollment_url.md", - "sha256": "8f8c3a95cadf263ae4af32e882455bf9dc0fa176ce48d5930a90575fad7a7286", - "size": 2221 + "sha256": "4e2a18efdf06be7e53847ce82f7a62f7cf8f2c7a53723e1b0b32428deaade94b", + "size": 2476 }, { "url": "https://platform.claude.com/docs/en/api/admin", @@ -4771,6 +7424,209 @@ "sha256": "bebae0d75b22cbb34be23794c71b98c36106cf1e1aefd9e6c5e042a69d985ded", "size": 3986 }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/agent-loop", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/agent-loop.md", + "sha256": "676787d1b81260a94dd7f743428d975022fe6b590777c741703b19c8be90cba5", + "size": 33828 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/claude-code-features", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/claude-code-features.md", + "sha256": "90af7023e59de84c376a78bb04e862ae76818147582db8acae5b2669edd7a8d0", + "size": 19484 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/cost-tracking", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/cost-tracking.md", + "sha256": "c69dd346b2e14ef764f33d593f3c6293cd5ec81ffab61c49e269b2ea543fa8bc", + "size": 11943 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/custom-tools", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/custom-tools.md", + "sha256": "4c4270e2ca267cb725234302b8495a6685b895f63e6fd7c10825d9e06e726446", + "size": 35868 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/file-checkpointing", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/file-checkpointing.md", + "sha256": "a2c0735332ff8bc51bcb386ec362339804cbc6cdc8adccb466f62bee3c459b2e", + "size": 29478 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/hooks", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/hooks.md", + "sha256": "216940c760dd7af41cea7741553d5aebe8c72e2d2fb164a18ab6157850f99fb5", + "size": 38329 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/hosting", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/hosting.md", + "sha256": "9e62437d7283c4f33c286f541cf5de3c410b326300223a4562018075fa7608c4", + "size": 6934 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/mcp", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/mcp.md", + "sha256": "1008a0a2580372d2ab90dc09c50f15451bfad82896e422e9ecfa2398e63ce591", + "size": 24246 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/migration-guide", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/migration-guide.md", + "sha256": "6371f9a2d7030dd0ed2634bb698f5428b27734a4e537afb1c8732c3d1b023c97", + "size": 9632 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/modifying-system-prompts.md", + "sha256": "e511a8d79c07e66369c683e410dd79cb9a1b87ba6702f70a64161f56ece4c003", + "size": 15707 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/observability", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/observability.md", + "sha256": "c929a4b2401cfc2659af5a72e637647343943120adae8da5f87660a48edd3763", + "size": 12002 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/overview", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/overview.md", + "sha256": "520c00e11831725b36058a11dbe2c349837a5bb2165fc397e7c2cfbaf8037d43", + "size": 22438 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/permissions", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/permissions.md", + "sha256": "d6b5cc38e5f06092b6e1f0c7571fc2ce7167f656367f24c26c13c6f11696ce58", + "size": 12417 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/plugins", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/plugins.md", + "sha256": "b4ca2c4fa6584b17497c7fa1813e7f99ca5c1d840f420964cb109f43352157d1", + "size": 11176 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/python", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/python.md", + "sha256": "886a5a42f7c792ba04f8e5a77ab312f489a4a19c82ac143622c3000b16636537", + "size": 134595 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/quickstart", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/quickstart.md", + "sha256": "cd6c11642e55dc79772ed6f9ab53cc7b9f812901607bec4a158482f1516a8a02", + "size": 12805 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/secure-deployment", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/secure-deployment.md", + "sha256": "9cf8f31cf3f60fe0bb3be2e67aff7bb55f4a2f1be6c3c5d5eb9a4e8d18c96029", + "size": 23926 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/sessions", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/sessions.md", + "sha256": "438e949d6ef91016c38cddb82cd0dcdb6c0e70d7f9f79d6677db9fde72ca7781", + "size": 17496 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/skills", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/skills.md", + "sha256": "d1f29bd96bf4ddc70d3afa66650f6934a54ae49607b7d88dafd8294776360e09", + "size": 11094 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/slash-commands", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/slash-commands.md", + "sha256": "d79aa19c9f124c5f3ec126394daab9f5658a4df25b7ccd1cb38cb787a5b81c5f", + "size": 13932 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/streaming-output", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/streaming-output.md", + "sha256": "fc207d0e76406b4a93aacd0d3afb0f85cdd6c4c79aaa8fe4b7194b8df91fc752", + "size": 15623 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/streaming-vs-single-mode.md", + "sha256": "e370739f0d8eb03aca81453b5d51768e0c3a43d7a2abbdae16e744ac2d438e82", + "size": 8241 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/structured-outputs", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/structured-outputs.md", + "sha256": "f28f041eb42895353cbd2670fbceaf076b6c826e82048e819257a2960194443f", + "size": 16368 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/subagents", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/subagents.md", + "sha256": "32a0ad30cfaeb56914a8531311f61de02cfc96b8ec4d3b291274778fe190a27a", + "size": 27214 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/todo-tracking", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/todo-tracking.md", + "sha256": "042ff23363e69632ff7c7747c5933dc8a3b4d4205ee267cdb8d98a99c432ff71", + "size": 6468 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/tool-search", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/tool-search.md", + "sha256": "805a4674b379bda96382603d303e18311e6635a23aa1c4cc36eea4826c1055fd", + "size": 7660 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/typescript", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/typescript.md", + "sha256": "de17bb899856e58c4e86266356f8214fc9ec0a4c3392db9c6c2ec216b4a59a9a", + "size": 102979 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/typescript-v2-preview", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/typescript-v2-preview.md", + "sha256": "d21079d7c43eae641da9c98a838ce7f50fdb8293b41863eff4ca2f8dbe031646", + "size": 11513 + }, + { + "url": "https://code.claude.com/docs/en/agent-sdk/user-input", + "status": "success", + "path": "en/docs/claude-code/agent-sdk/user-input.md", + "sha256": "426883b8e81bb144f18848b4715d914afa77b450967e0a28ab5336cb47a700a1", + "size": 35116 + }, { "url": "https://code.claude.com/docs/en/agent-teams", "status": "success", @@ -4796,8 +7652,8 @@ "url": "https://code.claude.com/docs/en/authentication", "status": "success", "path": "en/docs/claude-code/authentication.md", - "sha256": "0ba8fe2b803c153a0b50f4ea2d77a57347072b4197bfd40b37486c6a4ef89de3", - "size": 8665 + "sha256": "7ae4c818ae2ea6a2c84c7be4bb92b2e96de31fe780ba6ccd19187dcf06f5c12f", + "size": 8820 }, { "url": "https://code.claude.com/docs/en/best-practices", @@ -4810,8 +7666,8 @@ "url": "https://code.claude.com/docs/en/changelog", "status": "success", "path": "en/docs/claude-code/changelog.md", - "sha256": "934d2c7d2867699dd232bb0f2a846743d5ca32474c2ef5fcd8bfa306d0ab28df", - "size": 219591 + "sha256": "de5bfe30f5e4e7121388da67547883638ba974e24e94efda9619f64e32f2ffba", + "size": 225215 }, { "url": "https://code.claude.com/docs/en/channels", @@ -4845,22 +7701,22 @@ "url": "https://code.claude.com/docs/en/claude-code-on-the-web", "status": "success", "path": "en/docs/claude-code/claude-code-on-the-web.md", - "sha256": "3431d5e9ac6579b710b9b3ad84db9c00e6f3c581484bc5ffb8cd9306e07de335", - "size": 31434 + "sha256": "f827f1c7698d60c8c9fecde82a7bdc29f2d108e6a038d84b68ec43e934dbca9f", + "size": 44317 }, { "url": "https://code.claude.com/docs/en/claude-directory", "status": "success", "path": "en/docs/claude-code/claude-directory.md", - "sha256": "8ae71b7164b213ab92238bb9238878a6f70c030fcd7ce2fd190aa5081495452b", - "size": 74366 + "sha256": "09d89c354e7f6f1b5bf62ce546dd314ce3aa40f402333a251c84aa8df2e8e6ef", + "size": 75568 }, { "url": "https://code.claude.com/docs/en/cli-reference", "status": "success", "path": "en/docs/claude-code/cli-reference.md", - "sha256": "fc2feb45850d29107d29a574cefac6d69473e6393e77e210cc3380d07de0e183", - "size": 36699 + "sha256": "d6647c691652979f9db1dab3e0fefd56f20563ba57109b911d7260ee56c7c312", + "size": 36667 }, { "url": "https://code.claude.com/docs/en/code-review", @@ -4873,8 +7729,8 @@ "url": "https://code.claude.com/docs/en/commands", "status": "success", "path": "en/docs/claude-code/commands.md", - "sha256": "79ce76854ea20e60006b525728a24ac70fd21d08c923121f2d070766b8da6efb", - "size": 28948 + "sha256": "59429b6d18b6bf5afbf52e4fc7ffb9098355ae6d06c3c51cc1789ba1f66b0354", + "size": 49654 }, { "url": "https://code.claude.com/docs/en/common-workflows", @@ -4908,15 +7764,15 @@ "url": "https://code.claude.com/docs/en/data-usage", "status": "success", "path": "en/docs/claude-code/data-usage.md", - "sha256": "9c87929fa542877df182e31f47a54f096bb8d95c651137969d891f921d18f106", - "size": 10850 + "sha256": "b9d4ac7515dff014c8fcdb8a13ed6a2517046dc799ee09cde27dd264b433e42f", + "size": 10851 }, { "url": "https://code.claude.com/docs/en/desktop", "status": "success", "path": "en/docs/claude-code/desktop.md", - "sha256": "f9b693208c3e454ad64886284dc5f85bbd16e3ce4a1ca6c8b98c97599e666d84", - "size": 51102 + "sha256": "df0970cb873092ecfffcf8e1e943400e77b5d1cb6db25196aef4f67fb946c623", + "size": 52417 }, { "url": "https://code.claude.com/docs/en/desktop-quickstart", @@ -4936,8 +7792,8 @@ "url": "https://code.claude.com/docs/en/devcontainer", "status": "success", "path": "en/docs/claude-code/devcontainer.md", - "sha256": "586b43a1b3677c6e63d8fc2f9b11cc6e866562359d57ffbd14b3ac9bab4c34c2", - "size": 4643 + "sha256": "38ed6ca20d09624a01215d5fd31a6a13ffe8e2850ddff266459da09d9b31e990", + "size": 4984 }, { "url": "https://code.claude.com/docs/en/discover-plugins", @@ -4950,15 +7806,15 @@ "url": "https://code.claude.com/docs/en/env-vars", "status": "success", "path": "en/docs/claude-code/env-vars.md", - "sha256": "27f9cb40c0deb24f7a9a040416cf6bf2b0ecbcaef1c6786b94e998245132a2f4", - "size": 123738 + "sha256": "caa97918dde55bcc555303e633c3467f9b44a91b7bdd1adebc28c4db5765dfbf", + "size": 124393 }, { "url": "https://code.claude.com/docs/en/fast-mode", "status": "success", "path": "en/docs/claude-code/fast-mode.md", - "sha256": "f1d458ae23db0f577a786718cc387190f4efbc020d4d7a6818b23b8064c94810", - "size": 8275 + "sha256": "6741462f186f5a68e9a9700f6dfe2b0d6aac30e7cb8c916881c78ab9f28d1bb3", + "size": 8267 }, { "url": "https://code.claude.com/docs/en/features-overview", @@ -4971,29 +7827,29 @@ "url": "https://code.claude.com/docs/en/fullscreen", "status": "success", "path": "en/docs/claude-code/fullscreen.md", - "sha256": "9b6a58286e00d4afd953dcd4d937f593071ea5b68f7a2b4e54d043561a1df22e", - "size": 12402 + "sha256": "65894d1c77273a7b82328f22de28b607d63e61d03cf6adc73c3c13c2b7a56477", + "size": 13020 }, { "url": "https://code.claude.com/docs/en/github-actions", "status": "success", "path": "en/docs/claude-code/github-actions.md", - "sha256": "f63c3c13f3939d391e934caf08467e1dde8f4b14ffc69bcc8459f645c9892699", - "size": 28434 + "sha256": "5e8b598c4975fcdcd506692827f9a12b729fac096e5db8a00239a047e6498b7a", + "size": 28402 }, { "url": "https://code.claude.com/docs/en/github-enterprise-server", "status": "success", "path": "en/docs/claude-code/github-enterprise-server.md", - "sha256": "cdaa5bd08c4dfa457790cc916a2ec20026d3f0387935ebf3031cafbdde0f05fe", - "size": 11723 + "sha256": "8a43439aca273e772d554ea379105a84db09cd73b0d9eb661df2b96088799d6e", + "size": 11701 }, { "url": "https://code.claude.com/docs/en/gitlab-ci-cd", "status": "success", "path": "en/docs/claude-code/gitlab-ci-cd.md", - "sha256": "ea2982a52c6669996bec5537e55b9645398f5c4304c7e65ec34752051b0fcff0", - "size": 17895 + "sha256": "403923d27de2e04959367f1316130f1757b1ae209e23db823e04f1cd722c6f98", + "size": 17863 }, { "url": "https://code.claude.com/docs/en/google-vertex-ai", @@ -5006,8 +7862,8 @@ "url": "https://code.claude.com/docs/en/headless", "status": "success", "path": "en/docs/claude-code/headless.md", - "sha256": "2960850eed7fc9a4a5b4aa3c3a4cf9024b56517d49f7148d17d5ac5d8e963a0c", - "size": 12083 + "sha256": "6d508abfd775c9a201b551ea1d776df3438472b549b8e8a088f315f0ccc65875", + "size": 11984 }, { "url": "https://code.claude.com/docs/en/hooks", @@ -5027,15 +7883,15 @@ "url": "https://code.claude.com/docs/en/how-claude-code-works", "status": "success", "path": "en/docs/claude-code/how-claude-code-works.md", - "sha256": "2014a550fffb07f12680e50d0201c05a3fb8f469638f0a1dc572a627cbdfdc62", - "size": 18956 + "sha256": "4820117d801535abc9b1126144afbb72b5b444eac75e2ada55002d8100647a5c", + "size": 19349 }, { "url": "https://code.claude.com/docs/en/interactive-mode", "status": "success", "path": "en/docs/claude-code/interactive-mode.md", - "sha256": "0b2292d10c66406fa841f82bf4ce7a12a1bef596eb6f401e28c2fd1426b9c37c", - "size": 22702 + "sha256": "db806dad79e126641880a77b1212dfc4ec7f2a4fe64057ec781c35a3a5c40495", + "size": 25362 }, { "url": "https://code.claude.com/docs/en/jetbrains", @@ -5055,8 +7911,8 @@ "url": "https://code.claude.com/docs/en/legal-and-compliance", "status": "success", "path": "en/docs/claude-code/legal-and-compliance.md", - "sha256": "a2a0ff9d93f11130f49db108b11d3f5230ab72d75d47bf68500fbef297cbe33c", - "size": 3554 + "sha256": "c04a21cf44168e80e8cd48a4e48a3c5ffdc7a5df86459ebb8f9911cd4f8c398b", + "size": 3522 }, { "url": "https://code.claude.com/docs/en/llm-gateway", @@ -5069,8 +7925,8 @@ "url": "https://code.claude.com/docs/en/mcp", "status": "success", "path": "en/docs/claude-code/mcp.md", - "sha256": "eadae5848c052ba4a21b5e1e3e414a1f1a28558850e12b7c3a824451a9ef8c97", - "size": 54206 + "sha256": "201207d00416d9d94f9839dbca571c125caeed674e62ace1e527b3ec6336b77f", + "size": 54765 }, { "url": "https://code.claude.com/docs/en/memory", @@ -5097,8 +7953,8 @@ "url": "https://code.claude.com/docs/en/monitoring-usage", "status": "success", "path": "en/docs/claude-code/monitoring-usage.md", - "sha256": "e1fd996bddbdbd5d4f23c8aa27b54fbd9b0c0c833a1a18976831ad25c7e76e32", - "size": 32533 + "sha256": "a3cce49b0e886b6fd49e6682c607bb38b3eedb5373c8c737415915d83db205fb", + "size": 32883 }, { "url": "https://code.claude.com/docs/en/network-config", @@ -5118,29 +7974,29 @@ "url": "https://code.claude.com/docs/en/overview", "status": "success", "path": "en/docs/claude-code/overview.md", - "sha256": "60033e68fcf1665774fd7be5e8d68aaeccbbc8f11f14c16591638e8f10650629", - "size": 14281 + "sha256": "a40f718d1091886334b94e611892889811e37d87b026ee87a499ab9ed68b5e2c", + "size": 16147 }, { "url": "https://code.claude.com/docs/en/permission-modes", "status": "success", "path": "en/docs/claude-code/permission-modes.md", - "sha256": "ae12a0e2f315c57788eb392be988b5e3eb4196daba0b8da280dc064226d1c1bb", - "size": 17163 + "sha256": "447c47108be5af675140244172d168169178d3d0d321ae1d70f898f37429b216", + "size": 17826 }, { "url": "https://code.claude.com/docs/en/permissions", "status": "success", "path": "en/docs/claude-code/permissions.md", - "sha256": "28bc705a4862999466e54fe614d982b1aed2ba71eb90109f3acf93dda5ad6724", - "size": 32298 + "sha256": "5d277a8484a3b4229f72a34bd5d06015023922eef358b6c811d1062035a70aa7", + "size": 32570 }, { "url": "https://code.claude.com/docs/en/platforms", "status": "success", "path": "en/docs/claude-code/platforms.md", - "sha256": "0677c881e51bed1aa18d71f17e5df816aba53c0c8ca2ef364ee1c1bf732b5b40", - "size": 9536 + "sha256": "68932d5004d161d91c1c675bdacc6213f76d2141e68a50b3325f925bfb33de33", + "size": 10519 }, { "url": "https://code.claude.com/docs/en/plugin-marketplaces", @@ -5209,42 +8065,42 @@ "url": "https://code.claude.com/docs/en/settings", "status": "success", "path": "en/docs/claude-code/settings.md", - "sha256": "8820b9b3e23b0a01b594d6968374e94b503f4e2699532228a2e55c096dd664ea", - "size": 94226 + "sha256": "4729207ed7812fc33b24d155a512ec5bdfab198fc6745550d0619157ca2b90f1", + "size": 94641 }, { "url": "https://code.claude.com/docs/en/setup", "status": "success", "path": "en/docs/claude-code/setup.md", - "sha256": "de8cc3649f3d49ee1f8e6d04d381757f81d1095c9796ecaa35fe411fb2112337", - "size": 16138 + "sha256": "daf138bc358b5279118890698877b40546759fd1292d1590fca27ff1951d1d23", + "size": 16677 }, { "url": "https://code.claude.com/docs/en/skills", "status": "success", "path": "en/docs/claude-code/skills.md", - "sha256": "62c3e6b4d975c38c9229d9a8cc51a4b3ae7c21a24287d6e1a83924e00e6ffd5c", - "size": 42296 + "sha256": "268bfb971488551c60c514fce4b8250ee8d4a53ebc8ab70188f0cab0e7d2ccbd", + "size": 44055 }, { "url": "https://code.claude.com/docs/en/slack", "status": "success", "path": "en/docs/claude-code/slack.md", - "sha256": "b8e7deeb3ff9dddd1793c607934b1dde9166919818ada305f97b70ae825e7a1e", - "size": 13420 + "sha256": "21114ade74a5f8d40399e66faa0fd6b88ee6169ab883ebfa207c9d26ed40f741", + "size": 13532 }, { "url": "https://code.claude.com/docs/en/statusline", "status": "success", "path": "en/docs/claude-code/statusline.md", - "sha256": "41cc3cd8da43d13414ee4e140b39af3e3b89cc696f8674de171a4e91f265f1de", - "size": 49026 + "sha256": "b93ff6c7630a912ce4c25e6215d64fca709efa21635ce94313640006188eaaf8", + "size": 52439 }, { "url": "https://code.claude.com/docs/en/sub-agents", "status": "success", "path": "en/docs/claude-code/sub-agents.md", - "sha256": "3a548045d93ff854bd29427de573a09abfdbf930d139c22a1f624745e69a916b", + "sha256": "a3c94361f8760842d81a90835be771dae04d28dcc91dc5e24acc3dcb0534417b", "size": 51255 }, { @@ -5272,15 +8128,15 @@ "url": "https://code.claude.com/docs/en/troubleshooting", "status": "success", "path": "en/docs/claude-code/troubleshooting.md", - "sha256": "f7ef007ec48e33218701c1300a7cf54b732fd9b77872ff7a60d6066adde99fce", - "size": 39022 + "sha256": "945a914b705847020a7e241ea4f9adfa41637a8613d98945eb0fd387f9012fcf", + "size": 40336 }, { "url": "https://code.claude.com/docs/en/ultraplan", "status": "success", "path": "en/docs/claude-code/ultraplan.md", - "sha256": "5c8508b004e8e8b0b734a4f8fb4e6eb946926c6f313dfec6cd9d26d60387c5ba", - "size": 5998 + "sha256": "a910bac0b3b0d00a3f93af19eab13d2f9f41991cb19c1797a1913b32cca55ee6", + "size": 5952 }, { "url": "https://code.claude.com/docs/en/voice-dictation", @@ -5296,12 +8152,19 @@ "sha256": "073dbe9429a3d8d29e878390f030b6723adc19c818bf112ceacd828b27f351cb", "size": 37867 }, + { + "url": "https://code.claude.com/docs/en/web-quickstart", + "status": "success", + "path": "en/docs/claude-code/web-quickstart.md", + "sha256": "68413411e89239d52bb7d12cecb467c41daa3bbba23e17be09bebc7027ba5db5", + "size": 15545 + }, { "url": "https://code.claude.com/docs/en/web-scheduled-tasks", "status": "success", "path": "en/docs/claude-code/web-scheduled-tasks.md", - "sha256": "a215d5ded10b20b8ae6b91e00d5352f0ed292bda04422cd31d3af86ac9198a04", - "size": 10532 + "sha256": "c90fcaaaeadcc0a1fc5bcc23b673901ed2fe1fb9dc173b99a3febb796e97e24f", + "size": 10984 }, { "url": "https://code.claude.com/docs/en/whats-new/2026-w13", @@ -5314,8 +8177,8 @@ "url": "https://code.claude.com/docs/en/whats-new/2026-w14", "status": "success", "path": "en/docs/claude-code/whats-new/2026-w14.md", - "sha256": "fb9c317d9dff35c4ea0f65942ef4186f73e02927c89760d8cf9b9fc871c779b0", - "size": 7694 + "sha256": "afeedc6f3dfe80ff5bc089613beb7c3c327569d5b3be5f700a6afa8730e1edd8", + "size": 7700 }, { "url": "https://code.claude.com/docs/en/whats-new/index", @@ -5342,14 +8205,14 @@ "url": "https://www.anthropic.com/engineering/claude-code-best-practices", "status": "success", "path": "blog/engineering/claude-code-best-practices.md", - "sha256": "876799d698588cb1a619231d985430633e66823e6bb77dd6f55d6e48fe28a4b3", - "size": 43860 + "sha256": "07b1b951dfb3b9694e0fe1f34c1abdd191f04525921e4c00206d0cab66c02bed", + "size": 43925 }, { "url": "https://www.anthropic.com/engineering/claude-code-sandboxing", "status": "success", "path": "blog/engineering/claude-code-sandboxing.md", - "sha256": "ec74dc9ac2caa00489c33665c1ab3ea238127a79361e371fb0a294a81d8f088f", + "sha256": "2247936081b84944053453299b757401beda09e04be9bfdda397149084f0fd7f", "size": 8687 }, { @@ -5389,8 +8252,8 @@ } ], "summary": { - "total": 769, - "downloaded": 769, + "total": 1178, + "downloaded": 1178, "skipped": 0, "failed": 0, "success_rate": 100.0 diff --git a/content/CHANGELOG.md b/content/CHANGELOG.md index b60430972..32933facf 100644 --- a/content/CHANGELOG.md +++ b/content/CHANGELOG.md @@ -1,5 +1,54 @@ # Changelog +## 2.1.97 + +- Added focus view toggle (`Ctrl+O`) in `NO_FLICKER` mode showing prompt, one-line tool summary with edit diffstats, and final response +- Added `refreshInterval` status line setting to re-run the status line command every N seconds +- Added `workspace.git_worktree` to the status line JSON input, set when the current directory is inside a linked git worktree +- Added `● N running` indicator in `/agents` next to agent types with live subagent instances +- Added syntax highlighting for Cedar policy files (`.cedar`, `.cedarpolicy`) +- Fixed `--dangerously-skip-permissions` being silently downgraded to accept-edits mode after approving a write to a protected path +- Fixed and hardened Bash tool permissions, tightening checks around env-var prefixes and network redirects, and reducing false prompts on common commands +- Fixed permission rules with names matching JavaScript prototype properties (e.g. `toString`) causing `settings.json` to be silently ignored +- Fixed managed-settings allow rules remaining active after an admin removed them until process restart +- Fixed `permissions.additionalDirectories` changes in settings not applying mid-session +- Fixed removing a directory from `settings.permissions.additionalDirectories` revoking access to the same directory passed via `--add-dir` +- Fixed MCP HTTP/SSE connections accumulating ~50 MB/hr of unreleased buffers when servers reconnect +- Fixed MCP OAuth `oauth.authServerMetadataUrl` not being honored on token refresh after restart, fixing ADFS and similar IdPs +- Fixed 429 retries burning all attempts in ~13 seconds when the server returns a small `Retry-After` — exponential backoff now applies as a minimum +- Fixed rate-limit upgrade options disappearing after context compaction +- Fixed several `/resume` picker issues: `--resume ` opening uneditable, Ctrl+A reload wiping search, empty list swallowing navigation, task-status text replacing conversation summary, and cross-project staleness +- Fixed file-edit diffs disappearing on `--resume` when the edited file was larger than 10KB +- Fixed `--resume` cache misses and lost mid-turn input from attachment messages not being saved to the transcript +- Fixed messages typed while Claude is working not being persisted to the transcript +- Fixed prompt-type `Stop`/`SubagentStop` hooks failing on long sessions, and hook evaluator API errors displaying "JSON validation failed" instead of the actual message +- Fixed subagents with worktree isolation or `cwd:` override leaking their working directory back to the parent session's Bash tool +- Fixed compaction writing duplicate multi-MB subagent transcript files on prompt-too-long retries +- Fixed `claude plugin update` reporting "already at the latest version" for git-based marketplace plugins when the remote had newer commits +- Fixed slash command picker breaking when a plugin's frontmatter `name` is a YAML boolean keyword +- Fixed copying wrapped URLs in `NO_FLICKER` mode inserting spaces at line breaks +- Fixed scroll rendering artifacts in `NO_FLICKER` mode when running inside zellij +- Fixed a crash in `NO_FLICKER` mode when hovering over MCP tool results +- Fixed a `NO_FLICKER` mode memory leak where API retries left stale streaming state +- Fixed slow mouse-wheel scrolling in `NO_FLICKER` mode on Windows Terminal +- Fixed custom status line not displaying in `NO_FLICKER` mode on terminals shorter than 24 rows +- Fixed Shift+Enter and Alt/Cmd+arrow shortcuts not working in Warp with `NO_FLICKER` mode +- Fixed Korean/Japanese/Unicode text becoming garbled when copied in no-flicker mode on Windows +- Fixed Bedrock SigV4 authentication failing when `AWS_BEARER_TOKEN_BEDROCK` or `ANTHROPIC_BEDROCK_BASE_URL` are set to empty strings (as GitHub Actions does for unset inputs) +- Improved Accept Edits mode to auto-approve filesystem commands prefixed with safe env vars or process wrappers (e.g. `LANG=C rm foo`, `timeout 5 mkdir out`) +- Improved auto mode and bypass-permissions mode to auto-approve sandbox network access prompts +- Improved sandbox: `sandbox.network.allowMachLookup` now takes effect on macOS +- Improved image handling: pasted and attached images are now compressed to the same token budget as images read via the Read tool +- Improved slash command and `@`-mention completion to trigger after CJK sentence punctuation, so Japanese/Chinese input no longer requires a space before `/` or `@` +- Improved Bridge sessions to show the local git repo, branch, and working directory on the claude.ai session card +- Improved footer layout: indicators (Focus, notifications) now stay on the mode-indicator row instead of wrapping below +- Improved context-low warning to show as a transient footer notification instead of a persistent row +- Improved markdown blockquotes to show a continuous left bar across wrapped lines +- Improved session transcript size by skipping empty hook entries and capping stored pre-edit file copies +- Improved transcript accuracy: per-block entries now carry the final token usage instead of the streaming placeholder +- Improved Bash tool OTEL tracing: subprocesses now inherit a W3C `TRACEPARENT` env var when tracing is enabled +- Updated `/claude-api` skill to cover Managed Agents alongside the Claude API + ## 2.1.96 - Fixed Bedrock requests failing with `403 "Authorization header is missing"` when using `AWS_BEARER_TOKEN_BEDROCK` or `CLAUDE_CODE_SKIP_BEDROCK_AUTH` (regression in 2.1.94) diff --git a/content/blog/engineering/claude-code-best-practices.md b/content/blog/engineering/claude-code-best-practices.md index 97d5308c6..0ae4560f3 100644 --- a/content/blog/engineering/claude-code-best-practices.md +++ b/content/blog/engineering/claude-code-best-practices.md @@ -29,7 +29,7 @@ Use Claude Code Best Practices for Claude Code -[Getting started](https://www.anthropic.com/docs/en/overview)[Build with Claude Code](https://www.anthropic.com/docs/en/sub-agents)[Deployment](https://www.anthropic.com/docs/en/third-party-integrations)[Administration](https://www.anthropic.com/docs/en/setup)[Configuration](https://www.anthropic.com/docs/en/settings)[Reference](https://www.anthropic.com/docs/en/cli-reference)[What's New](https://www.anthropic.com/docs/en/whats-new)[Resources](https://www.anthropic.com/docs/en/legal-and-compliance) +[Getting started](https://www.anthropic.com/docs/en/overview)[Build with Claude Code](https://www.anthropic.com/docs/en/sub-agents)[Deployment](https://www.anthropic.com/docs/en/third-party-integrations)[Administration](https://www.anthropic.com/docs/en/setup)[Configuration](https://www.anthropic.com/docs/en/settings)[Reference](https://www.anthropic.com/docs/en/cli-reference)[Agent SDK](https://www.anthropic.com/docs/en/agent-sdk/overview)[What's New](https://www.anthropic.com/docs/en/whats-new)[Resources](https://www.anthropic.com/docs/en/legal-and-compliance) ##### Getting started @@ -125,7 +125,7 @@ Claude performs dramatically better when it can verify its own work, like run te | Strategy | Before | After | | --- | --- | --- | -| **Provide verification criteria** | _”implement a function that validates email addresses"_ | _"write a validateEmail function. example test cases: [[email protected]](https://www.anthropic.com/cdn-cgi/l/email-protection#7005031502301508111d001c155e131f1d) is true, invalid is false, [[email protected]](https://www.anthropic.com/cdn-cgi/l/email-protection#b8cdcbddcaf896dbd7d5) is false. run the tests after implementing”_ | +| **Provide verification criteria** | _”implement a function that validates email addresses"_ | _"write a validateEmail function. example test cases: [[email protected]](https://www.anthropic.com/cdn-cgi/l/email-protection#423731273002273a232f322e276c212d2f) is true, invalid is false, [[email protected]](https://www.anthropic.com/cdn-cgi/l/email-protection#0d787e687f4d236e6260) is false. run the tests after implementing”_ | | **Verify UI changes visually** | _”make the dashboard look better"_ | _"[paste screenshot] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them”_ | | **Address root causes, not symptoms** | _”the build is failing"_ | _"the build fails with this error: [paste error]. fix it and verify the build succeeds. address the root cause, don’t suppress the error”_ | diff --git a/content/blog/engineering/claude-code-sandboxing.md b/content/blog/engineering/claude-code-sandboxing.md index 9543db71a..88a62029e 100644 --- a/content/blog/engineering/claude-code-sandboxing.md +++ b/content/blog/engineering/claude-code-sandboxing.md @@ -68,7 +68,7 @@ Our new sandboxed bash tool and Claude Code on the web offer substantial improve To get started with these tools: 1. Run `/sandbox` in Claude and check out [our docs](https://docs.claude.com/en/docs/claude-code/sandboxing) on how to configure this sandbox. -2. Go to [claude.com/code](http://claude.ai/redirect/website.v1.91b9b576-38af-40d7-8b65-118a3bfcad75/code) to try out Claude Code on the web. +2. Go to [claude.com/code](http://claude.ai/redirect/website.v1.2c75e6bb-6a63-4eff-b77e-916242daf86e/code) to try out Claude Code on the web. Or, if you're building your own agents, check out our [open-sourced sandboxing code](https://github.com/anthropic-experimental/sandbox-runtime), and consider integrating it into your work. We look forward to seeing what you build. diff --git a/content/claude-code-manifest.json b/content/claude-code-manifest.json index d9ff28bd5..dbe0dd96e 100644 --- a/content/claude-code-manifest.json +++ b/content/claude-code-manifest.json @@ -1,12 +1,12 @@ { "name": "@anthropic-ai/claude-code", - "version": "2.1.96", + "version": "2.1.97", "author": { "name": "Anthropic", "email": "support@anthropic.com" }, "license": "SEE LICENSE IN README.md", - "_id": "@anthropic-ai/claude-code@2.1.96", + "_id": "@anthropic-ai/claude-code@2.1.97", "maintainers": [ { "name": "zak-anthropic", @@ -73,20 +73,20 @@ "claude": "cli.js" }, "dist": { - "shasum": "d528e9638292c7b275c896b283e4a8e6959ef0ef", - "tarball": "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-2.1.96.tgz", + "shasum": "b790d417b4f47b897068ffff9b57812ccc81e707", + "tarball": "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-2.1.97.tgz", "fileCount": 20, - "integrity": "sha512-ETrc0+1qWHaqtKi+ixbsAecZyM+H52VIJj+zWIvw3jBU/JZ9v5vnE2kHShM1lcpr+Gji7GXk23l0CMGLA7hC0g==", + "integrity": "sha512-8lKM/rFctBl+82bQ+0g0Lkbt9tJU/zYKAjWisNUq436/386n/VZQbnyjnibGkyqqB6mrX/3ub/cpFlpCu4FXLg==", "signatures": [ { - "sig": "MEUCIDfVFVFY0qtDRV8JGrx0/QKyh70/hWuV+lO0LSTt2zz6AiEA20JmCcoQACXgZOSLdrLxZ8I2356j3KvBbianSlhxu0A=", + "sig": "MEUCICG6rML8JBFMxvrHFFDhofBztC5mvsOLqHbO7G4bdU4MAiEA/TuR+/HzSBvE2e/5XokcLHWOLaw604eahZ4Hy+IFTew=", "keyid": "SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U" } ], - "unpackedSize": 48924836 + "unpackedSize": 48991994 }, "type": "module", - "_from": "file:/home/runner/work/claude-cli-internal/claude-cli-internal/build-external/anthropic-ai-claude-code-2.1.96.tgz", + "_from": "file:/home/runner/work/claude-cli-internal/claude-cli-internal/build-external/anthropic-ai-claude-code-2.1.97.tgz", "engines": { "node": ">=18.0.0" }, @@ -97,8 +97,8 @@ "name": "wolffiex", "email": "wolffiex@anthropic.com" }, - "_resolved": "/home/runner/work/claude-cli-internal/claude-cli-internal/build-external/anthropic-ai-claude-code-2.1.96.tgz", - "_integrity": "sha512-ETrc0+1qWHaqtKi+ixbsAecZyM+H52VIJj+zWIvw3jBU/JZ9v5vnE2kHShM1lcpr+Gji7GXk23l0CMGLA7hC0g==", + "_resolved": "/home/runner/work/claude-cli-internal/claude-cli-internal/build-external/anthropic-ai-claude-code-2.1.97.tgz", + "_integrity": "sha512-8lKM/rFctBl+82bQ+0g0Lkbt9tJU/zYKAjWisNUq436/386n/VZQbnyjnibGkyqqB6mrX/3ub/cpFlpCu4FXLg==", "_npmVersion": "10.8.2", "description": "Use Claude, Anthropic's AI assistant, right from your terminal. Claude can understand your codebase, edit files, run terminal commands, and handle entire workflows for you.", "directories": {}, @@ -118,7 +118,7 @@ "@img/sharp-linuxmusl-arm64": "^0.34.2" }, "_npmOperationalInternal": { - "tmp": "tmp/claude-code_2.1.96_1775622763975_0.7218051294969574", + "tmp": "tmp/claude-code_2.1.97_1775683674825_0.4147276975853762", "host": "s3://npm-registry-packages-npm-production" } } \ No newline at end of file diff --git a/content/en/about-claude/models/migration-guide.md b/content/en/about-claude/models/migration-guide.md index 39f22c068..126c31341 100644 --- a/content/en/about-claude/models/migration-guide.md +++ b/content/en/about-claude/models/migration-guide.md @@ -4,6 +4,10 @@ Guide for migrating to Claude 4.6 models from previous Claude versions --- + +This guide covers migrating [Messages API](/docs/en/build-with-claude/working-with-messages) code. If you use [Claude Managed Agents](/docs/en/managed-agents/overview), see [Migrating between model versions](/docs/en/managed-agents/migration#migrating-between-model-versions). The Managed Agents runtime handles most of the request-shape changes described here. + + ## Migrating to Claude 4.6 Claude Opus 4.6 is a near drop-in replacement for Claude 4.5, with a few breaking changes to be aware of. For a full list of new features, see [What's new in Claude 4.6](/docs/en/about-claude/models/whats-new-claude-4-6). @@ -50,6 +54,20 @@ These are not required but will improve your experience: ) ``` + ```bash CLI + ant messages create <<'YAML' + model: claude-opus-4-6 + max_tokens: 16000 + thinking: + type: adaptive + output_config: + effort: high + messages: + - role: user + content: Your prompt here + YAML + ``` + ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; @@ -222,7 +240,7 @@ model = "claude-opus-4-6" # After Use only `temperature` OR `top_p`, not both: - ```python nocheck + ```python Python nocheck # Before - This will error in Claude 4+ models response = client.messages.create( model="claude-3-7-sonnet-20250219", @@ -263,7 +281,7 @@ model = "claude-opus-4-6" # After Update your application to [handle `refusal` stop reasons](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals): - ```python nocheck + ```python Python nocheck response = client.messages.create(...) if response.stop_reason == "refusal": @@ -276,7 +294,7 @@ model = "claude-opus-4-6" # After Claude 4.5+ models return a `model_context_window_exceeded` stop reason when generation stops due to hitting the context window limit, rather than the requested `max_tokens` limit. Update your application to handle this new stop reason: - ```python nocheck + ```python Python nocheck response = client.messages.create(...) if response.stop_reason == "model_context_window_exceeded": @@ -436,6 +454,18 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create <<'YAML' +model: claude-sonnet-4-6 +max_tokens: 8192 +output_config: + effort: low +messages: + - role: user + content: Your prompt here +YAML +``` + ```python Python response = client.messages.create( model="claude-sonnet-4-6", @@ -615,6 +645,20 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI nocheck +ant messages create <<'YAML' +model: claude-sonnet-4-6 +max_tokens: 64000 +thinking: + type: adaptive +output_config: + effort: medium +messages: + - role: user + content: Your prompt here +YAML +``` + ```python Python nocheck response = client.messages.create( model="claude-sonnet-4-6", @@ -803,6 +847,21 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant beta:messages create --beta interleaved-thinking-2025-05-14 <<'YAML' +model: claude-sonnet-4-6 +max_tokens: 16384 +thinking: + type: enabled + budget_tokens: 16384 +output_config: + effort: medium +messages: + - role: user + content: Your prompt here +YAML +``` + ```python Python response = client.beta.messages.create( model="claude-sonnet-4-6", @@ -995,6 +1054,21 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant beta:messages create --beta interleaved-thinking-2025-05-14 <<'YAML' +model: claude-sonnet-4-6 +max_tokens: 8192 +thinking: + type: enabled + budget_tokens: 16384 +output_config: + effort: low +messages: + - role: user + content: Your prompt here +YAML +``` + ```python Python response = client.beta.messages.create( model="claude-sonnet-4-6", diff --git a/content/en/about-claude/models/whats-new-claude-4-6.md b/content/en/about-claude/models/whats-new-claude-4-6.md index 58be69ac7..39ec2ffb0 100644 --- a/content/en/about-claude/models/whats-new-claude-4-6.md +++ b/content/en/about-claude/models/whats-new-claude-4-6.md @@ -25,7 +25,7 @@ For complete pricing and specs, see the [models overview](/docs/en/about-claude/ `thinking: {type: "enabled"}` and `budget_tokens` are **deprecated** on Opus 4.6 and Sonnet 4.6. They remain functional but will be removed in a future model release. Use adaptive thinking and the [effort parameter](/docs/en/build-with-claude/effort) to control thinking depth instead. Adaptive thinking also automatically enables interleaved thinking. -```python +```python Python response = client.messages.create( model="claude-opus-4-6", max_tokens=16000, @@ -66,7 +66,7 @@ The following tools are now generally available: [Fast mode](/docs/en/build-with-claude/fast-mode) (`speed: "fast"`) delivers significantly faster output token generation for Opus models. Fast mode is up to 2.5x as fast at premium pricing ($30/$150 per MTok). This is the same model running with faster inference (no change to intelligence or capabilities). -```python +```python Python response = client.beta.messages.create( model="claude-opus-4-6", max_tokens=4096, @@ -106,7 +106,7 @@ On **Sonnet 4.6**, the `interleaved-thinking-2025-05-14` beta header is still fu The `output_format` parameter for [structured outputs](/docs/en/build-with-claude/structured-outputs) has been moved to `output_config.format`. The old parameter remains functional but is deprecated and will be removed in a future model release. -```python nocheck +```python Python nocheck # Before response = client.messages.create( output_format={"type": "json_schema", "schema": {...}}, diff --git a/content/en/about-claude/pricing.md b/content/en/about-claude/pricing.md index 97345912c..85bdfb7d8 100644 --- a/content/en/about-claude/pricing.md +++ b/content/en/about-claude/pricing.md @@ -281,41 +281,67 @@ Computer use follows the standard [tool use pricing](/docs/en/agents-and-tools/t If you're also using bash or text editor tools alongside computer use, those tools have their own token costs as documented in their respective pages. -## Agent use case pricing examples +## Claude Managed Agents pricing -Understanding pricing for agent applications is crucial when building with Claude. These real-world examples can help you estimate costs for different agent patterns. +[Claude Managed Agents](/docs/en/managed-agents/overview) is billed on two dimensions: tokens and session runtime. -### Customer support agent example +### Tokens -When building a customer support agent, here's how costs might break down: +All tokens consumed by a Claude Managed Agents session are billed at the rates shown in [Model pricing](#model-pricing) above. [Prompt caching](#prompt-caching) multipliers apply identically. Web search triggered inside a session incurs the standard $10 per 1,000 searches. + +The following Messages API modifiers do **not** apply to Claude Managed Agents sessions: + +| Modifier | Why it doesn't apply | +| --- | --- | +| [Batch API discount](#batch-processing) | Sessions are stateful and interactive. There is no batch mode. | +| [Fast mode premium](#fast-mode-pricing) | Inference speed is managed by the runtime. | +| [Data residency multiplier](#data-residency-pricing) | `inference_geo` is a Messages API request field. | +| [Long context premium](#long-context-pricing) | Context window is managed by the runtime. | +| [Third-party platform pricing](#third-party-platform-pricing) | Claude Managed Agents is available only through the Claude API directly. | + +### Session runtime + +| SKU | Rate | Metering | +| --- | --- | --- | +| Session runtime | $0.08 per session-hour | `running` status duration | + +Runtime is measured to the millisecond and accrues only while the session's status is `running`. Time spent `idle` (waiting for your next message or a tool confirmation), `rescheduling`, or `terminated` does not count toward runtime. - Example calculation for processing 10,000 support tickets: - - Average ~3,700 tokens per conversation - - Using Claude Opus 4.6 at $5/MTok input, $25/MTok output - - Total cost: ~$37.00 per 10,000 tickets +Session runtime replaces the [Code Execution](#code-execution-tool) container-hour billing model when using Claude Managed Agents. You are not separately billed for container hours on top of session runtime. -For a detailed walkthrough of this calculation, see the [customer support agent guide](/docs/en/about-claude/use-case-guides/customer-support-chat). +### Worked example -### General agent workflow pricing +A one-hour coding session using Claude Opus 4.6 that consumes 50,000 input tokens and 15,000 output tokens: -For more complex agent architectures with multiple steps: +| Line item | Calculation | Cost | +| --- | --- | --- | +| Input tokens | 50,000 × $5 / 1,000,000 | $0.25 | +| Output tokens | 15,000 × $25 / 1,000,000 | $0.375 | +| Session runtime | 1.0 hour × $0.08 | $0.08 | +| **Total** | | **$0.705** | -1. **Initial request processing** - - Typical input: 500-1,000 tokens - - Processing cost: ~$0.003 per request +If prompt caching is active and 40,000 of the input tokens are cache reads: -2. **Memory and context retrieval** - - Retrieved context: 2,000-5,000 tokens - - Cost per retrieval: ~$0.015 per operation +| Line item | Calculation | Cost | +| --- | --- | --- | +| Uncached input tokens | 10,000 × $5 / 1,000,000 | $0.05 | +| Cache read tokens | 40,000 × $5 × 0.1 / 1,000,000 | $0.02 | +| Output tokens | 15,000 × $25 / 1,000,000 | $0.375 | +| Session runtime | 1.0 hour × $0.08 | $0.08 | +| **Total** | | **$0.525** | -3. **Action planning and execution** - - Planning tokens: 1,000-2,000 - - Execution feedback: 500-1,000 - - Combined cost: ~$0.045 per action + + Example calculation for processing 10,000 support tickets: + - Average ~3,700 tokens per conversation + - Using Claude Opus 4.6 at $5/MTok input, $25/MTok output + - Total cost: ~$37.00 per 10,000 tickets + -For a comprehensive guide on agent pricing patterns, see the [agent use cases guide](/docs/en/about-claude/use-case-guides). +For a detailed walkthrough of this calculation, see the [customer support agent guide](/docs/en/about-claude/use-case-guides/customer-support-chat). + +## Additional pricing considerations ### Cost optimization strategies @@ -330,8 +356,6 @@ When building agents with Claude: For high-volume agent applications, contact the [enterprise sales team](https://claude.com/contact-sales) for custom pricing arrangements. -## Additional pricing considerations - ### Rate limits Rate limits vary by usage tier and affect how many requests you can make: diff --git a/content/en/about-claude/use-case-guides/content-moderation.md b/content/en/about-claude/use-case-guides/content-moderation.md index 22b37fa36..fb67b95ef 100644 --- a/content/en/about-claude/use-case-guides/content-moderation.md +++ b/content/en/about-claude/use-case-guides/content-moderation.md @@ -113,7 +113,7 @@ When selecting a model, it’s important to consider the size of your data. If c In order to use Claude for content moderation, Claude must understand the moderation requirements of your application. Let’s start by writing a prompt that allows you to define your moderation needs: -```python nocheck hidelines={1} +```python Python nocheck hidelines={1} import anthropic import json @@ -190,7 +190,7 @@ Content moderation is a classification problem. Thus, you can use the same techn One additional consideration is that instead of treating content moderation as a binary classification problem, you may instead create multiple categories to represent various risk levels. Creating multiple risk levels allows you to adjust the aggressiveness of your moderation. For example, you might want to automatically block user queries that are deemed high risk, while users with many medium risk queries are flagged for human review. -```python nocheck hidelines={1} +```python Python nocheck hidelines={1} import anthropic import json @@ -289,7 +289,7 @@ In complex scenarios, it may be helpful to consider additional strategies to imp In addition to listing the unsafe categories in the prompt, further improvements can be made by providing definitions and phrases related to each category. -```python nocheck hidelines={1} +```python Python nocheck hidelines={1} import anthropic import json @@ -387,7 +387,7 @@ Notably, the definition for the `Specialized Advice` category now specifies the To reduce costs in situations where real-time moderation isn't necessary, consider moderating messages in batches. Include multiple messages within the prompt's context, and ask Claude to assess which messages should be moderated. -```python nocheck hidelines={1} +```python Python nocheck hidelines={1} import anthropic import json @@ -456,6 +456,7 @@ Violated Categories: {", ".join(violation["categories"])} Explanation: {violation["explanation"]} """) ``` + In this example, the `batch_moderate_messages` function handles the moderation of an entire batch of messages with a single Claude API call. Inside the function, a prompt is created that includes the list of messages to evaluate, the defined unsafe content categories, and their descriptions. The prompt directs Claude to return a JSON object listing all messages that contain violations. Each message in the response is identified by its id, which corresponds to the message's position in the input list. Keep in mind that finding the optimal batch size for your specific needs may require some experimentation. While larger batch sizes can lower costs, they might also lead to a slight decrease in quality. Additionally, you may need to increase the `max_tokens` parameter in the Claude API call to accommodate longer responses. For details on the maximum number of tokens your chosen model can output, refer to the [model comparison page](/docs/en/about-claude/models#model-comparison-table). diff --git a/content/en/about-claude/use-case-guides/legal-summarization.md b/content/en/about-claude/use-case-guides/legal-summarization.md index ac8ec5001..7d02228f4 100644 --- a/content/en/about-claude/use-case-guides/legal-summarization.md +++ b/content/en/about-claude/use-case-guides/legal-summarization.md @@ -152,7 +152,7 @@ Claude can adapt to various summarization styles. You can change the details of Here’s an example of how to create a prompt that ensures the generated summaries follow a consistent structure when analyzing sublease agreements: -```python nocheck hidelines={1..2} +```python Python nocheck hidelines={1..2} import anthropic # Initialize the Anthropic client @@ -252,7 +252,7 @@ Legal summarization often involves handling long documents or many related docum Here's an example of how to perform meta-summarization: -```python nocheck hidelines={1..2} +```python Python nocheck hidelines={1..2} import anthropic # Initialize the Anthropic client diff --git a/content/en/about-claude/use-case-guides/ticket-routing.md b/content/en/about-claude/use-case-guides/ticket-routing.md index 27da05445..cb1cd7c09 100644 --- a/content/en/about-claude/use-case-guides/ticket-routing.md +++ b/content/en/about-claude/use-case-guides/ticket-routing.md @@ -344,7 +344,7 @@ It’s hard to know how well your prompt works without deploying it in a test pr Let’s build the deployment structure. Start by defining the method signature for wrapping our call to Claude. We'll take the method we’ve already begun to write, which has `ticket_contents` as input, and now return a tuple of `reasoning` and `intent` as output. If you have an existing automation using traditional ML, you'll want to follow that method signature instead. -```python nocheck hidelines={1} +```python Python nocheck hidelines={1} import anthropic import re @@ -410,7 +410,7 @@ You may need to assess Claude on other axes depending on what factors that are i To assess this, we first have to modify the script we wrote and add a function to compare the predicted intent with the actual intent and calculate the percentage of correct predictions. We also have to add in cost calculation and time measurement functionality. -```python nocheck hidelines={1} +```python Python nocheck hidelines={1} import anthropic import re diff --git a/content/en/agents-and-tools/agent-skills/best-practices.md b/content/en/agents-and-tools/agent-skills/best-practices.md index 70b6bffc7..25bb1d4f6 100644 --- a/content/en/agents-and-tools/agent-skills/best-practices.md +++ b/content/en/agents-and-tools/agent-skills/best-practices.md @@ -1127,13 +1127,6 @@ Before sharing a Skill, verify: > Create and manage Skills in Claude Code - - Use Skills programmatically in TypeScript and Python - Upload and manage Skills programmatically - - Security patterns for agent deployment - \ No newline at end of file diff --git a/content/en/agents-and-tools/agent-skills/overview.md b/content/en/agents-and-tools/agent-skills/overview.md index 66a0fc601..dad4aaa53 100644 --- a/content/en/agents-and-tools/agent-skills/overview.md +++ b/content/en/agents-and-tools/agent-skills/overview.md @@ -177,16 +177,6 @@ Custom Skills in Claude Code are filesystem-based and don't require API uploads. To learn more, see [Use Skills in Claude Code](https://code.claude.com/docs/en/skills). -### Claude Agent SDK - -The [Claude Agent SDK](/docs/en/agent-sdk/overview) supports custom Skills through filesystem-based configuration. - -**Custom Skills**: Create Skills as directories with SKILL.md files in `.claude/skills/`. Enable Skills by including `"Skill"` in your `allowed_tools` configuration. - -Skills in the Agent SDK are then automatically discovered when the SDK runs. - -To learn more, see [Agent Skills in the SDK](/docs/en/agent-sdk/skills). - ### Claude.ai [Claude.ai](https://claude.ai) supports both pre-built Agent Skills and custom Skills. @@ -344,13 +334,6 @@ Plan your Skills to work within these constraints. > Create and manage custom Skills in Claude Code - - Use Skills programmatically in TypeScript and Python - + +```bash Shell +curl "https://api.anthropic.com/v1/skills?source=anthropic" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "anthropic-beta: skills-2025-10-02" +``` + +```bash CLI +ant beta:skills list --source anthropic +``` + ```python Python import anthropic @@ -57,13 +68,6 @@ for (const skill of skills.data) { console.log(`${skill.id}: ${skill.display_title}`); } ``` - -```bash Shell -curl "https://api.anthropic.com/v1/skills?source=anthropic" \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "anthropic-beta: skills-2025-10-02" -``` You see the following Skills: `pptx`, `xlsx`, `docx`, and `pdf`. @@ -75,6 +79,56 @@ This API returns each Skill's metadata: its name and description. Claude loads t Now use the PowerPoint Skill to create a presentation about renewable energy. Specify Skills using the `container` parameter in the Messages API: +```bash Shell +curl https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 4096, + "container": { + "skills": [ + { + "type": "anthropic", + "skill_id": "pptx", + "version": "latest" + } + ] + }, + "messages": [{ + "role": "user", + "content": "Create a presentation about renewable energy with 5 slides" + }], + "tools": [{ + "type": "code_execution_20250825", + "name": "code_execution" + }] + }' +``` + +```bash CLI +ant beta:messages create \ + --beta code-execution-2025-08-25 \ + --beta skills-2025-10-02 \ + --transform content <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +container: + skills: + - type: anthropic + skill_id: pptx + version: latest +messages: + - role: user + content: Create a presentation about renewable energy with 5 slides +tools: + - type: code_execution_20250825 + name: code_execution +YAML +``` + ```python Python import anthropic @@ -135,35 +189,6 @@ const response = await client.beta.messages.create({ console.log(response.content); ``` - -```bash Shell -curl https://api.anthropic.com/v1/messages \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \ - -H "content-type: application/json" \ - -d '{ - "model": "claude-opus-4-6", - "max_tokens": 4096, - "container": { - "skills": [ - { - "type": "anthropic", - "skill_id": "pptx", - "version": "latest" - } - ] - }, - "messages": [{ - "role": "user", - "content": "Create a presentation about renewable energy with 5 slides" - }], - "tools": [{ - "type": "code_execution_20250825", - "name": "code_execution" - }] - }' -``` Let's break down what each part does: @@ -183,6 +208,50 @@ The presentation was created in the code execution container and saved as a file +```bash Shell nocheck +# Extract file_id from response (using jq) +FILE_ID=$(echo "$RESPONSE" | jq -r '.content[] | select(.type=="tool_use" and .name=="code_execution") | .content[] | select(.file_id) | .file_id') + +# Download the file +curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "anthropic-beta: files-api-2025-04-14" \ + --output renewable_energy.pptx + +echo "Presentation saved to renewable_energy.pptx" +``` + +```bash CLI +# Extract file_id with --transform on the messages create call +FILE_ID=$(ant beta:messages create \ + --beta code-execution-2025-08-25 --beta skills-2025-10-02 \ + --transform 'content.#.content.content.#.file_id|@flatten|0' \ + --format yaml <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +container: + skills: + - type: anthropic + skill_id: pptx + version: latest +messages: + - role: user + content: Create a presentation about renewable energy with 5 slides +tools: + - type: code_execution_20250825 + name: code_execution +YAML +) + +# Download the file +ant beta:files download \ + --file-id "$FILE_ID" \ + --output renewable_energy.pptx + +printf 'Presentation saved to renewable_energy.pptx\n' +``` + ```python Python nocheck from typing import Any @@ -238,20 +307,6 @@ if (fileId) { console.log("Presentation saved to renewable_energy.pptx"); } ``` - -```bash Shell nocheck -# Extract file_id from response (using jq) -FILE_ID=$(echo "$RESPONSE" | jq -r '.content[] | select(.type=="tool_use" and .name=="code_execution") | .content[] | select(.file_id) | .file_id') - -# Download the file -curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "anthropic-beta: files-api-2025-04-14" \ - --output renewable_energy.pptx - -echo "Presentation saved to renewable_energy.pptx" -``` @@ -265,6 +320,55 @@ Now that you've created your first document with Skills, try these variations: ### Create a spreadsheet +```bash Shell +curl https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 4096, + "container": { + "skills": [ + { + "type": "anthropic", + "skill_id": "xlsx", + "version": "latest" + } + ] + }, + "messages": [{ + "role": "user", + "content": "Create a quarterly sales tracking spreadsheet with sample data" + }], + "tools": [{ + "type": "code_execution_20250825", + "name": "code_execution" + }] + }' +``` + +```bash CLI +ant beta:messages create \ + --beta code-execution-2025-08-25 \ + --beta skills-2025-10-02 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +container: + skills: + - type: anthropic + skill_id: xlsx + version: latest +messages: + - role: user + content: Create a quarterly sales tracking spreadsheet with sample data +tools: + - type: code_execution_20250825 + name: code_execution +YAML +``` + ```python Python response = client.beta.messages.create( model="claude-opus-4-6", @@ -311,7 +415,11 @@ const response = await client.beta.messages.create({ ] }); ``` + +### Create a Word document + + ```bash Shell curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ @@ -325,14 +433,14 @@ curl https://api.anthropic.com/v1/messages \ "skills": [ { "type": "anthropic", - "skill_id": "xlsx", + "skill_id": "docx", "version": "latest" } ] }, "messages": [{ "role": "user", - "content": "Create a quarterly sales tracking spreadsheet with sample data" + "content": "Write a 2-page report on the benefits of renewable energy" }], "tools": [{ "type": "code_execution_20250825", @@ -340,11 +448,27 @@ curl https://api.anthropic.com/v1/messages \ }] }' ``` - -### Create a Word document +```bash CLI +ant beta:messages create \ + --beta code-execution-2025-08-25 \ + --beta skills-2025-10-02 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +container: + skills: + - type: anthropic + skill_id: docx + version: latest +messages: + - role: user + content: Write a 2-page report on the benefits of renewable energy +tools: + - type: code_execution_20250825 + name: code_execution +YAML +``` - ```python Python response = client.beta.messages.create( model="claude-opus-4-6", @@ -391,7 +515,11 @@ const response = await client.beta.messages.create({ ] }); ``` + +### Generate a PDF + + ```bash Shell curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ @@ -405,14 +533,14 @@ curl https://api.anthropic.com/v1/messages \ "skills": [ { "type": "anthropic", - "skill_id": "docx", + "skill_id": "pdf", "version": "latest" } ] }, "messages": [{ "role": "user", - "content": "Write a 2-page report on the benefits of renewable energy" + "content": "Generate a PDF invoice template" }], "tools": [{ "type": "code_execution_20250825", @@ -420,11 +548,27 @@ curl https://api.anthropic.com/v1/messages \ }] }' ``` - -### Generate a PDF +```bash CLI +ant beta:messages create \ + --beta code-execution-2025-08-25 \ + --beta skills-2025-10-02 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +container: + skills: + - type: anthropic + skill_id: pdf + version: latest +messages: + - role: user + content: Generate a PDF invoice template +tools: + - type: code_execution_20250825 + name: code_execution +YAML +``` - ```python Python response = client.beta.messages.create( model="claude-opus-4-6", @@ -466,35 +610,6 @@ const response = await client.beta.messages.create({ ] }); ``` - -```bash Shell -curl https://api.anthropic.com/v1/messages \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \ - -H "content-type: application/json" \ - -d '{ - "model": "claude-opus-4-6", - "max_tokens": 4096, - "container": { - "skills": [ - { - "type": "anthropic", - "skill_id": "pdf", - "version": "latest" - } - ] - }, - "messages": [{ - "role": "user", - "content": "Generate a PDF invoice template" - }], - "tools": [{ - "type": "code_execution_20250825", - "name": "code_execution" - }] - }' -``` ## Next steps @@ -530,13 +645,6 @@ Now that you've used pre-built Agent Skills, you can: > Learn about Skills in Claude Code - - Use Skills programmatically in TypeScript and Python - - Use the [`mcp_servers` API parameter](#using-the-mcp-connector-in-the-messages-api) when you have remote servers accessible via URL and only need tool support. If you're using the [Agent SDK](/docs/en/agent-sdk/mcp), MCP connections are managed automatically. Use the client-side helpers when you need local servers, prompts, resources, or more control over the connection with the base SDK. + Use the [`mcp_servers` API parameter](#using-the-mcp-connector-in-the-messages-api) when you have remote servers accessible via URL and only need tool support. Use the client-side helpers when you need local servers, prompts, resources, or more control over the connection with the base SDK. ### Installation diff --git a/content/en/agents-and-tools/tool-use/bash-tool.md b/content/en/agents-and-tools/tool-use/bash-tool.md index 0e33e90dc..79b95beee 100644 --- a/content/en/agents-and-tools/tool-use/bash-tool.md +++ b/content/en/agents-and-tools/tool-use/bash-tool.md @@ -28,23 +28,6 @@ For model support, see the [Tool reference](/docs/en/agents-and-tools/tool-use/t ## Quick start -```python Python -import anthropic - -client = anthropic.Anthropic() - -response = client.messages.create( - model="claude-opus-4-6", - max_tokens=1024, - tools=[{"type": "bash_20250124", "name": "bash"}], - messages=[ - {"role": "user", "content": "List all Python files in the current directory."} - ], -) - -print(response) -``` - ```bash Shell curl https://api.anthropic.com/v1/messages \ -H "content-type: application/json" \ @@ -67,6 +50,31 @@ curl https://api.anthropic.com/v1/messages \ ] }' ``` + +```bash CLI +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --tool '{type: bash_20250124, name: bash}' \ + --message '{role: user, content: List all Python files in the current directory.}' +``` + +```python Python +import anthropic + +client = anthropic.Anthropic() + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + tools=[{"type": "bash_20250124", "name": "bash"}], + messages=[ + {"role": "user", "content": "List all Python files in the current directory."} + ], +) + +print(response) +``` ## How it works diff --git a/content/en/agents-and-tools/tool-use/code-execution-tool.md b/content/en/agents-and-tools/tool-use/code-execution-tool.md index 7e3120685..062a18484 100644 --- a/content/en/agents-and-tools/tool-use/code-execution-tool.md +++ b/content/en/agents-and-tools/tool-use/code-execution-tool.md @@ -68,6 +68,14 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 4096 \ + --message '{role: user, content: "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"}' \ + --tool '{type: code_execution_20250825, name: code_execution}' +``` + ```python Python hidelines={1..2} import anthropic @@ -345,6 +353,31 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI hidelines={1} +printf 'name,value\nfoo,1\nbar,2\n' > data.csv +# Upload a file +FILE_ID=$(ant beta:files upload \ + --file ./data.csv \ + --transform id --format yaml) + +# Use the file_id with code execution +ant beta:messages create \ + --beta files-api-2025-04-14 < +```bash CLI nocheck +# Request code execution that creates files; extract file_ids from tool results +TOOL_RESULT='content.#(type=="bash_code_execution_tool_result")#' +FILE_IDS=$(ant beta:messages create \ + --beta files-api-2025-04-14 \ + --transform "${TOOL_RESULT}.content.content|@flatten|#.file_id" \ + --format yaml \ + --model claude-opus-4-6 \ + --max-tokens 4096 \ + --message '{role: user, content: Create a matplotlib visualization and save it as output.png}' \ + --tool '{type: code_execution_20250825, name: code_execution}' +) + +# Download each created file +while IFS= read -r LINE; do + [[ "$LINE" != "- "* ]] && continue + FILE_ID="${LINE#- }" + FILENAME=$(ant beta:files retrieve-metadata \ + --file-id "$FILE_ID" \ + --transform filename --format yaml) + ant beta:files download \ + --file-id "$FILE_ID" \ + --output "$FILENAME" > /dev/null + printf 'Downloaded: %s\n' "$FILENAME" +done <<< "$FILE_IDS" +``` + ```python Python nocheck hidelines={1..2} from anthropic import Anthropic @@ -1063,7 +1123,7 @@ The code execution tool can return two types of results depending on the operati ### Bash command response -```json hidelines={1,-1} +```json Output hidelines={1,-1} [ { "type": "server_tool_use", @@ -1089,7 +1149,7 @@ The code execution tool can return two types of results depending on the operati ### File operation responses **View file:** -```json hidelines={1,-1} +```json Output hidelines={1,-1} [ { "type": "server_tool_use", @@ -1116,7 +1176,7 @@ The code execution tool can return two types of results depending on the operati ``` **Create file:** -```json hidelines={1,-1} +```json Output hidelines={1,-1} [ { "type": "server_tool_use", @@ -1140,7 +1200,7 @@ The code execution tool can return two types of results depending on the operati ``` **Edit file (str_replace):** -```json hidelines={1,-1} +```json Output hidelines={1,-1} [ { "type": "server_tool_use", @@ -1185,7 +1245,7 @@ Additional fields for file operations: Each tool type can return specific errors: **Common errors (all tools):** -```json +```json Output { "type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR", @@ -1296,6 +1356,24 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +# First request: Create a file with a random number +CONTAINER_ID=$(ant messages create \ + --transform container.id --format yaml \ + --model claude-opus-4-6 \ + --max-tokens 4096 \ + --message '{role: user, content: Write a file with a random number and save it to "/tmp/number.txt"}' \ + --tool '{type: code_execution_20250825, name: code_execution}' +) + +# Second request: Reuse the container to read the file +ant messages create --container "$CONTAINER_ID" \ + --model claude-opus-4-6 \ + --max-tokens 4096 \ + --message '{role: user, content: Read the number from "/tmp/number.txt" and calculate its square}' \ + --tool '{type: code_execution_20250825, name: code_execution}' +``` + ```python Python hidelines={1..6} import os from anthropic import Anthropic diff --git a/content/en/agents-and-tools/tool-use/computer-use-tool.md b/content/en/agents-and-tools/tool-use/computer-use-tool.md index 67000cb10..5fe985fe5 100644 --- a/content/en/agents-and-tools/tool-use/computer-use-tool.md +++ b/content/en/agents-and-tools/tool-use/computer-use-tool.md @@ -102,6 +102,26 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant beta:messages create --beta computer-use-2025-11-24 <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +tools: + - type: computer_20251124 + name: computer + display_width_px: 1024 + display_height_px: 768 + display_number: 1 + - type: text_editor_20250728 + name: str_replace_based_edit_tool + - type: bash_20250124 + name: bash +messages: + - role: user + content: Save a picture of a cat to my desktop. +YAML +``` + ```python Python hidelines={1..2} import anthropic diff --git a/content/en/agents-and-tools/tool-use/fine-grained-tool-streaming.md b/content/en/agents-and-tools/tool-use/fine-grained-tool-streaming.md index a5e88ebaf..7bf188071 100644 --- a/content/en/agents-and-tools/tool-use/fine-grained-tool-streaming.md +++ b/content/en/agents-and-tools/tool-use/fine-grained-tool-streaming.md @@ -60,6 +60,33 @@ Here's an example of how to use fine-grained tool streaming with the API: }' ``` + ```bash CLI + ant messages create --stream \ + --transform usage <<'YAML' + model: claude-opus-4-6 + max_tokens: 65536 + tools: + - name: make_file + description: Write text to a file + eager_input_streaming: true + input_schema: + type: object + properties: + filename: + type: string + description: The filename to write text to + lines_of_text: + type: array + description: An array of lines of text to write to the file + required: + - filename + - lines_of_text + messages: + - role: user + content: Can you write a long poem and make a file called poem.txt? + YAML + ``` + ```python Python hidelines={1..2} import anthropic diff --git a/content/en/agents-and-tools/tool-use/memory-tool.md b/content/en/agents-and-tools/tool-use/memory-tool.md index e7b53e50b..0dbc6bdfb 100644 --- a/content/en/agents-and-tools/tool-use/memory-tool.md +++ b/content/en/agents-and-tools/tool-use/memory-tool.md @@ -134,6 +134,35 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +````bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 2048 +tools: + - type: memory_20250818 + name: memory +messages: + - role: user + content: | + I'm working on a Python web scraper that keeps crashing with a + timeout error. Here's the problematic function: + + ```python + def fetch_page(url, retries=3): + for i in range(retries): + try: + response = requests.get(url, timeout=5) + return response.text + except requests.exceptions.Timeout: + if i == retries - 1: + raise + time.sleep(1) + ``` + + Please help me debug this. +YAML +```` + ```python Python hidelines={1..2} import anthropic diff --git a/content/en/agents-and-tools/tool-use/overview.md b/content/en/agents-and-tools/tool-use/overview.md index e2ea42493..f0085d4c7 100644 --- a/content/en/agents-and-tools/tool-use/overview.md +++ b/content/en/agents-and-tools/tool-use/overview.md @@ -9,6 +9,27 @@ Tool use lets Claude call functions you define or that Anthropic provides. Claud Here's the simplest example using a server tool, where Anthropic handles execution: +```bash Shell +curl https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 1024, + "tools": [{"type": "web_search_20260209", "name": "web_search"}], + "messages": [{"role": "user", "content": "What'\''s the latest on the Mars rover?"}] + }' +``` + +```bash CLI +ant messages create --transform content --format yaml \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --tool '{type: web_search_20260209, name: web_search}' \ + --message '{role: user, content: "What is the latest on the Mars rover?"}' +``` + ```python Python import anthropic @@ -34,19 +55,6 @@ const response = await client.messages.create({ }); console.log(response.content); ``` - -```bash Shell -curl https://api.anthropic.com/v1/messages \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "content-type: application/json" \ - -d '{ - "model": "claude-opus-4-6", - "max_tokens": 1024, - "tools": [{"type": "web_search_20260209", "name": "web_search"}], - "messages": [{"role": "user", "content": "What'\''s the latest on the Mars rover?"}] - }' -``` --- diff --git a/content/en/agents-and-tools/tool-use/programmatic-tool-calling.md b/content/en/agents-and-tools/tool-use/programmatic-tool-calling.md index 78ba43f0c..9792864e9 100644 --- a/content/en/agents-and-tools/tool-use/programmatic-tool-calling.md +++ b/content/en/agents-and-tools/tool-use/programmatic-tool-calling.md @@ -65,6 +65,35 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: >- + Query sales data for the West, East, and Central regions, then + tell me which region had the highest revenue +tools: + - type: code_execution_20260120 + name: code_execution + - name: query_database + description: >- + Execute a SQL query against the sales database. Returns a list + of rows as JSON objects. + input_schema: + type: object + properties: + sql: + type: string + description: SQL query to execute + required: + - sql + allowed_callers: + - code_execution_20260120 +YAML +``` + ```python Python import anthropic @@ -471,7 +500,7 @@ The request shape is identical to the [Quick start](#quick-start) example: inclu Claude writes code that calls your tool. The API pauses and returns: -```json +```json Output { "role": "assistant", "content": [ @@ -512,6 +541,44 @@ Include the full conversation history plus your tool result: +```bash CLI nocheck +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +container: container_xyz789 +messages: + - role: user + content: >- + Query customer purchase history from the last quarter and identify our + top 5 customers by revenue + - role: assistant + content: + - type: text + text: I'll query the purchase history and analyze the results. + - type: server_tool_use + id: srvtoolu_abc123 + name: code_execution + input: + code: "..." + - type: tool_use + id: toolu_def456 + name: query_database + input: + sql: "" + caller: + type: code_execution_20260120 + tool_id: srvtoolu_abc123 + - role: user + content: + - type: tool_result + tool_use_id: toolu_def456 + content: >- + [{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", + "revenue": 38000}, ...] +tools: [...] +YAML +``` + ```python Python nocheck response = client.messages.create( model="claude-opus-4-6", @@ -940,7 +1007,7 @@ The code execution continues and processes the results. If additional tool calls Once the code execution completes, Claude provides the final response: -```json +```json Output { "content": [ { diff --git a/content/en/agents-and-tools/tool-use/text-editor-tool.md b/content/en/agents-and-tools/tool-use/text-editor-tool.md index 82dc286fa..6b8764039 100644 --- a/content/en/agents-and-tools/tool-use/text-editor-tool.md +++ b/content/en/agents-and-tools/tool-use/text-editor-tool.md @@ -54,6 +54,14 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --tool '{type: text_editor_20250728, name: str_replace_based_edit_tool, max_characters: 10000}' \ + --message '{role: user, content: There is a syntax error in my primes.py file. Can you help me fix it?}' +``` + ```python Python hidelines={1..2} import anthropic @@ -323,6 +331,14 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --tool '{type: text_editor_20250728, name: str_replace_based_edit_tool}' \ + --message '{role: user, content: There is a syntax error in my primes.py file. Can you help me fix it?}' +``` + ```python Python hidelines={1..2} import anthropic @@ -397,7 +413,7 @@ void main() { Claude uses the text editor tool first to view the file: -```json +```json Output { "id": "msg_01XAbCDeFgHiJkLmNoPQrStU", "model": "claude-opus-4-6", @@ -475,6 +491,69 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +tools: + - type: text_editor_20250728 + name: str_replace_based_edit_tool +messages: + - role: user + content: There's a syntax error in my primes.py file. Can you help me fix it? + - role: assistant + content: + - type: text + text: >- + I'll help you fix the syntax error in your primes.py file. First, + let me take a look at the file to identify the issue. + - type: tool_use + id: toolu_01AbCdEfGhIjKlMnOpQrStU + name: str_replace_based_edit_tool + input: + command: view + path: primes.py + - role: user + content: + - type: tool_result + tool_use_id: toolu_01AbCdEfGhIjKlMnOpQrStU + content: |- + 1: def is_prime(n): + 2: """Check if a number is prime.""" + 3: if n <= 1: + 4: return False + 5: if n <= 3: + 6: return True + 7: if n % 2 == 0 or n % 3 == 0: + 8: return False + 9: i = 5 + 10: while i * i <= n: + 11: if n % i == 0 or n % (i + 2) == 0: + 12: return False + 13: i += 6 + 14: return True + 15: + 16: def get_primes(limit): + 17: """Generate a list of prime numbers up to the given limit.""" + 18: primes = [] + 19: for num in range(2, limit + 1) + 20: if is_prime(num): + 21: primes.append(num) + 22: return primes + 23: + 24: def main(): + 25: """Main function to demonstrate prime number generation.""" + 26: limit = 100 + 27: prime_list = get_primes(limit) + 28: print(f"Prime numbers up to {limit}:") + 29: print(prime_list) + 30: print(f"Found {len(prime_list)} prime numbers.") + 31: + 32: if __name__ == "__main__": + 33: main() +YAML +``` + ```python Python response = client.messages.create( model="claude-opus-4-6", @@ -642,7 +721,7 @@ In the example above, the `view` tool result includes file contents with line nu Claude identifies the syntax error and uses the `str_replace` command to fix it: -```json +```json Output { "id": "msg_01VwXyZAbCdEfGhIjKlMnO", "model": "claude-opus-4-6", @@ -671,6 +750,38 @@ Claude identifies the syntax error and uses the `str_replace` command to fix it: Your application should then make the edit and return the result: +```bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +tools: + - type: text_editor_20250728 + name: str_replace_based_edit_tool +messages: + # Previous messages... + - role: assistant + content: + - type: text + text: >- + I found the syntax error in your primes.py file. In the `get_primes` + function, there is a missing colon (:) at the end of the for loop + line. Let me fix that for you. + - type: tool_use + id: toolu_01PqRsTuVwXyZAbCdEfGh + name: str_replace_based_edit_tool + input: + command: str_replace + path: primes.py + old_str: " for num in range(2, limit + 1)" + new_str: " for num in range(2, limit + 1):" + - role: user + content: + - type: tool_result + tool_use_id: toolu_01PqRsTuVwXyZAbCdEfGh + content: Successfully replaced text at exactly one location. +YAML +``` + ```python Python response = client.messages.create( model="claude-opus-4-6", @@ -838,7 +949,7 @@ public class TextEditorConversationExample { Finally, Claude provides a complete explanation of the fix: -```json +```json Output { "id": "msg_01IjKlMnOpQrStUvWxYzAb", "model": "claude-opus-4-6", diff --git a/content/en/agents-and-tools/tool-use/tool-search-tool.md b/content/en/agents-and-tools/tool-use/tool-search-tool.md index 6c1c3aa7d..e8c166eb4 100644 --- a/content/en/agents-and-tools/tool-use/tool-search-tool.md +++ b/content/en/agents-and-tools/tool-use/tool-search-tool.md @@ -110,6 +110,44 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 2048 +messages: + - role: user + content: What is the weather in San Francisco? +tools: + - type: tool_search_tool_regex_20251119 + name: tool_search_tool_regex + - name: get_weather + description: Get the weather at a specific location + input_schema: + type: object + properties: + location: + type: string + unit: + type: string + enum: [celsius, fahrenheit] + required: [location] + defer_loading: true + - name: search_files + description: Search through files in the workspace + input_schema: + type: object + properties: + query: + type: string + file_types: + type: array + items: + type: string + required: [query] + defer_loading: true +YAML +``` + ```python Python hidelines={1..2} import anthropic diff --git a/content/en/agents-and-tools/tool-use/web-fetch-tool.md b/content/en/agents-and-tools/tool-use/web-fetch-tool.md index 1f90db152..e4b47543a 100644 --- a/content/en/agents-and-tools/tool-use/web-fetch-tool.md +++ b/content/en/agents-and-tools/tool-use/web-fetch-tool.md @@ -82,6 +82,21 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: >- + Fetch the content at https://example.com/research-paper + and extract the key findings. +tools: + - type: web_fetch_20260209 + name: web_fetch +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -279,6 +294,14 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --message '{role: user, content: "Please analyze the content at https://example.com/article"}' \ + --tool '{type: web_fetch_20250910, name: web_fetch, max_uses: 5}' +``` + ```python Python hidelines={1..2} import anthropic @@ -516,7 +539,7 @@ When displaying API outputs directly to end users, citations must be included to Here's an example response structure: -```json +```json Output { "role": "assistant", "content": [ @@ -600,7 +623,7 @@ The web fetch tool caches results to improve performance and reduce redundant re For PDF documents, content is returned as base64-encoded data: -```json +```json Output { "type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_02", @@ -625,7 +648,7 @@ For PDF documents, content is returned as base64-encoded data: When the web fetch tool encounters an error, the Claude API returns a 200 (success) response with the error represented in the response body: -```json +```json Output { "type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_a93jad", @@ -661,7 +684,7 @@ The tool cannot fetch arbitrary URLs that Claude generates or URLs from containe Web fetch works seamlessly with web search for comprehensive information gathering: -```python hidelines={1..2} +```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() @@ -701,7 +724,7 @@ For caching tool definitions across turns, see [Tool use with prompt caching](/d With streaming enabled, fetch events are part of the stream with a pause during content retrieval: -```sse +```sse Output event: message_start data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}} diff --git a/content/en/agents-and-tools/tool-use/web-search-tool.md b/content/en/agents-and-tools/tool-use/web-search-tool.md index a70737131..91319102f 100644 --- a/content/en/agents-and-tools/tool-use/web-search-tool.md +++ b/content/en/agents-and-tools/tool-use/web-search-tool.md @@ -62,6 +62,21 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: >- + Search for the current prices of AAPL and GOOGL, then calculate + which has a better P/E ratio. +tools: + - type: web_search_20260209 + name: web_search +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -263,6 +278,14 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --message '{role: user, content: What is the weather in NYC?}' \ + --tool '{type: web_search_20250305, name: web_search, max_uses: 5}' +``` + ```python Python hidelines={1..2} import anthropic @@ -490,7 +513,7 @@ The `user_location` parameter allows you to localize search results based on a u Here's an example response structure: -```json +```json Output { "role": "assistant", "content": [ @@ -581,7 +604,7 @@ The web search citation fields `cited_text`, `title`, and `url` do not count tow When the web search tool encounters an error (such as hitting rate limits), the Claude API still returns a 200 (success) response. The error is represented within the response body using the following structure: -```json +```json Output { "type": "web_search_tool_result", "tool_use_id": "servertoolu_a93jad", @@ -612,7 +635,7 @@ For caching tool definitions across turns, see [Tool use with prompt caching](/d With streaming enabled, you'll receive search events as part of the stream. There will be a pause while the search executes: -```sse +```sse Output event: message_start data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}} diff --git a/content/en/api/beta-headers.md b/content/en/api/beta-headers.md index 1af561735..60927d33e 100644 --- a/content/en/api/beta-headers.md +++ b/content/en/api/beta-headers.md @@ -27,6 +27,29 @@ When using the SDK, you can specify beta headers in the request options: +```bash Shell +curl https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "anthropic-beta: files-api-2025-04-14" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 1024, + "messages": [ + {"role": "user", "content": "Hello, Claude"} + ] + }' +``` + +```bash CLI +ant beta:messages create \ + --beta files-api-2025-04-14 \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --message '{role: user, content: "Hello, Claude"}' +``` + ```python Python hidelines={1..2} from anthropic import Anthropic @@ -53,21 +76,6 @@ const msg = await anthropic.beta.messages.create({ }); ``` -```bash Shell -curl https://api.anthropic.com/v1/messages \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "anthropic-beta: files-api-2025-04-14" \ - -H "content-type: application/json" \ - -d '{ - "model": "claude-opus-4-6", - "max_tokens": 1024, - "messages": [ - {"role": "user", "content": "Hello, Claude"} - ] - }' -``` - @@ -86,6 +94,16 @@ To use multiple beta features in a single request, include all feature names in anthropic-beta: feature1,feature2,feature3 ``` +### Endpoint-specific headers + +Some beta features are scoped to specific endpoints rather than individual request parameters. [Claude Managed Agents](/docs/en/managed-agents/overview) uses a single beta header for all endpoints: + +| Endpoints | Beta header | +| --- | --- | +| `/v1/agents`, `/v1/sessions`, `/v1/environments` | `managed-agents-2026-04-01` | + +See the [Managed Agents overview](/docs/en/managed-agents/overview) for details. + ### Version naming conventions Beta feature names typically follow the pattern: `feature-name-YYYY-MM-DD`, where the date indicates when the beta version was released. Always use the exact beta feature name as documented. @@ -94,7 +112,7 @@ Beta feature names typically follow the pattern: `feature-name-YYYY-MM-DD`, wher If you use an invalid or unavailable beta header, you'll receive an error response: -```json +```json Output { "type": "error", "error": { diff --git a/content/en/api/beta.md b/content/en/api/beta.md index 10d283c01..bb43e6799 100644 --- a/content/en/api/beta.md +++ b/content/en/api/beta.md @@ -4,11 +4,11 @@ ### Anthropic Beta -- `AnthropicBeta = string or "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` +- `AnthropicBeta = string or "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -52,8 +52,6 @@ - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Beta API Error - `BetaAPIError = object { message, type }` @@ -338,7 +336,7 @@ The Models API response can be used to determine which models are available for - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -382,8 +380,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of BetaModelInfo` @@ -610,7 +606,7 @@ The Models API response can be used to determine information about a specific mo - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -654,8 +650,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaModelInfo = object { id, capabilities, created_at, 4 more }` @@ -1346,7 +1340,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -1390,8 +1384,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Body Parameters - `max_tokens: number` @@ -3979,15 +3971,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -6056,10 +6052,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. -- `user_profile_id: optional string` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - ### Returns - `BetaMessage = object { id, container, content, 8 more }` @@ -6983,15 +6975,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -7326,7 +7322,7 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -7370,8 +7366,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Body Parameters - `messages: array of BetaMessageParam` @@ -9951,15 +9945,19 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -11962,7 +11960,7 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ "role": "user" } ], - "model": "claude-opus-4-6" + "model": "claude-mythos-preview" }' ``` @@ -19151,15 +19149,19 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -24495,15 +24497,19 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -25739,15 +25745,19 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -34282,7 +34292,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -34326,8 +34336,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Body Parameters - `requests: array of object { custom_id, params }` @@ -34340,7 +34348,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Must be unique for each request within the Message Batch. - - `params: object { max_tokens, messages, model, 20 more }` + - `params: object { max_tokens, messages, model, 19 more }` Messages API creation parameters for the individual request. @@ -36931,15 +36939,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -39008,10 +39020,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id: optional string` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - ### Returns - `BetaMessageBatch = object { id, archived_at, cancel_initiated_at, 7 more }` @@ -39151,7 +39159,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -39195,365 +39203,359 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - -### Returns - -- `BetaMessageBatch = object { id, archived_at, cancel_initiated_at, 7 more }` - - - `id: string` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `archived_at: string` - - RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - - - `cancel_initiated_at: string` - - RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - - - `created_at: string` - - RFC 3339 datetime string representing the time at which the Message Batch was created. - - - `ended_at: string` - - RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. - - Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - - - `expires_at: string` - - RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - - - `processing_status: "in_progress" or "canceling" or "ended"` - - Processing status of the Message Batch. - - - `"in_progress"` - - - `"canceling"` - - - `"ended"` - - - `request_counts: BetaMessageBatchRequestCounts` - - Tallies requests within the Message Batch, categorized by their status. - - Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - - - `canceled: number` - - Number of requests in the Message Batch that have been canceled. - - This is zero until processing of the entire Message Batch has ended. - - - `errored: number` - - Number of requests in the Message Batch that encountered an error. - - This is zero until processing of the entire Message Batch has ended. - - - `expired: number` - - Number of requests in the Message Batch that have expired. - - This is zero until processing of the entire Message Batch has ended. - - - `processing: number` - - Number of requests in the Message Batch that are processing. - - - `succeeded: number` - - Number of requests in the Message Batch that have completed successfully. - - This is zero until processing of the entire Message Batch has ended. - - - `results_url: string` - - URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. - - Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - - - `type: "message_batch"` - - Object type. - - For Message Batches, this is always `"message_batch"`. - - - `"message_batch"` - -### Example - -```http -curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID \ - -H 'anthropic-version: 2023-06-01' \ - -H 'anthropic-beta: message-batches-2024-09-24' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" -``` - -## List - -**get** `/v1/messages/batches` - -List all Message Batches within a Workspace. Most recently created batches are returned first. - -Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) - -### Query Parameters - -- `after_id: optional string` - - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - -- `before_id: optional string` - - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - -- `limit: optional number` - - Number of items to return per page. - - Defaults to `20`. Ranges from `1` to `1000`. - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `data: array of BetaMessageBatch` - - - `id: string` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `archived_at: string` - - RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - - - `cancel_initiated_at: string` - - RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - - - `created_at: string` - - RFC 3339 datetime string representing the time at which the Message Batch was created. - - - `ended_at: string` - - RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. - - Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - - - `expires_at: string` - - RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - - - `processing_status: "in_progress" or "canceling" or "ended"` - - Processing status of the Message Batch. - - - `"in_progress"` - - - `"canceling"` - - - `"ended"` - - - `request_counts: BetaMessageBatchRequestCounts` - - Tallies requests within the Message Batch, categorized by their status. - - Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - - - `canceled: number` - - Number of requests in the Message Batch that have been canceled. - - This is zero until processing of the entire Message Batch has ended. - - - `errored: number` - - Number of requests in the Message Batch that encountered an error. - - This is zero until processing of the entire Message Batch has ended. - - - `expired: number` - - Number of requests in the Message Batch that have expired. - - This is zero until processing of the entire Message Batch has ended. - - - `processing: number` - - Number of requests in the Message Batch that are processing. - - - `succeeded: number` - - Number of requests in the Message Batch that have completed successfully. - - This is zero until processing of the entire Message Batch has ended. - - - `results_url: string` - - URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. - - Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - - - `type: "message_batch"` - - Object type. - - For Message Batches, this is always `"message_batch"`. - - - `"message_batch"` - -- `first_id: string` - - First ID in the `data` list. Can be used as the `before_id` for the previous page. - -- `has_more: boolean` - - Indicates if there are more results in the requested page direction. - -- `last_id: string` - - Last ID in the `data` list. Can be used as the `after_id` for the next page. - -### Example - -```http -curl https://api.anthropic.com/v1/messages/batches \ - -H 'anthropic-version: 2023-06-01' \ - -H 'anthropic-beta: message-batches-2024-09-24' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" -``` - -## Cancel - -**post** `/v1/messages/batches/{message_batch_id}/cancel` - -Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. - -The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. - -Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) - -### Path Parameters - -- `message_batch_id: string` - - ID of the Message Batch. - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` +### Returns + +- `BetaMessageBatch = object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: BetaMessageBatchRequestCounts` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + + - `"message_batch"` + +### Example + +```http +curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: message-batches-2024-09-24' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## List + +**get** `/v1/messages/batches` + +List all Message Batches within a Workspace. Most recently created batches are returned first. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Query Parameters + +- `after_id: optional string` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `before_id: optional string` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `limit: optional number` + + Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: array of BetaMessageBatch` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: BetaMessageBatchRequestCounts` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + + - `"message_batch"` + +- `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + +- `has_more: boolean` + + Indicates if there are more results in the requested page direction. + +- `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```http +curl https://api.anthropic.com/v1/messages/batches \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: message-batches-2024-09-24' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Cancel + +**post** `/v1/messages/batches/{message_batch_id}/cancel` + +Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. + +The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Path Parameters + +- `message_batch_id: string` + + ID of the Message Batch. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` ### Returns @@ -39679,7 +39681,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -39723,8 +39725,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaDeletedMessageBatch = object { id, type }` @@ -39775,7 +39775,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -39819,8 +39819,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatchIndividualResponse = object { custom_id, result }` @@ -40762,15 +40760,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -42335,15 +42337,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -43707,15 +43713,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -45041,12 +45051,447 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `UnionMember1 = string` + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `"assistant"` + + - `stop_details: BetaRefusalStopDetails` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `"refusal"` + + - `stop_reason: BetaStopReason` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `"message"` + + - `usage: BetaUsage` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: BetaCacheCreation` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: BetaIterationsUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `BetaMessageIterationUsage = object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: BetaCacheCreation` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `"message"` + + - `BetaCompactionIterationUsage = object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: BetaCacheCreation` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `"compaction"` + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: BetaServerToolUsage` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` + + - `"succeeded"` + +# Agents + +## Create + +**post** `/v1/agents` + +Create Agent + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `model: BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `BetaManagedAgentsModel = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `BetaManagedAgentsModelConfigParams = object { id, speed }` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-opus-4-6"` Most intelligent model for building agents and coding @@ -45079,276 +45524,22720 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ High-performance model for agents and coding - - `"claude-opus-4-1"` + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +- `name: string` + + Human-readable name for the agent. 1-256 characters. + +- `description: optional string` + + Description of what the agent does. Up to 2048 characters. + +- `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams` + + MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + +- `skills: optional array of BetaManagedAgentsSkillParams` + + Skills available to the agent. Maximum 20. + + - `BetaManagedAgentsAnthropicSkillParams = object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams = object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +- `system: optional string` + + System prompt for the agent. Up to 100,000 characters. + +- `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` + + Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `BetaManagedAgentsAgentToolset20260401Params = object { type, configs, default_config }` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` + + Per-tool configuration overrides. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsMCPToolsetParams = object { mcp_server_name, type, configs, default_config }` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsCustomToolParams = object { description, input_schema, name, type }` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + +### Returns + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```http +curl https://api.anthropic.com/v1/agents \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "model": "claude-sonnet-4-6", + "name": "My First Agent" + }' +``` + +## List + +**get** `/v1/agents` + +List Agents + +### Query Parameters + +- `"created_at[gte]": optional string` + + Return agents created at or after this time (inclusive). + +- `"created_at[lte]": optional string` + + Return agents created at or before this time (inclusive). + +- `include_archived: optional boolean` + + Include archived agents in results. Defaults to false. + +- `limit: optional number` + + Maximum results per page. Default 20, maximum 100. + +- `page: optional string` + + Opaque pagination cursor from a previous response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsAgent` + + List of agents. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/agents \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Path Parameters + +- `agent_id: string` + +### Query Parameters + +- `version: optional number` + + Agent version. Omit for the most recent version. Must be at least 1 if specified. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Path Parameters + +- `agent_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `version: number` + + The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + +- `description: optional string` + + Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + +- `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams` + + MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + +- `model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `BetaManagedAgentsModel = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `BetaManagedAgentsModelConfigParams = object { id, speed }` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +- `name: optional string` + + Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + +- `skills: optional array of BetaManagedAgentsSkillParams` + + Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `BetaManagedAgentsAnthropicSkillParams = object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams = object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +- `system: optional string` + + System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + +- `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` + + Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `BetaManagedAgentsAgentToolset20260401Params = object { type, configs, default_config }` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` + + Per-tool configuration overrides. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsMCPToolsetParams = object { mcp_server_name, type, configs, default_config }` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsCustomToolParams = object { description, input_schema, name, type }` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + +### Returns + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "version": 1 + }' +``` + +## Archive + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Path Parameters + +- `agent_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `BetaManagedAgentsAgentToolConfig = object { enabled, name, permission_policy }` + + Configuration for a specific agent tool. + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Tool Config Params + +- `BetaManagedAgentsAgentToolConfigParams = object { name, enabled, permission_policy }` + + Configuration override for a specific tool within a toolset. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config + +- `BetaManagedAgentsAgentToolsetDefaultConfig = object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `BetaManagedAgentsAgentToolsetDefaultConfigParams = object { enabled, permission_policy }` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset20260401 + +- `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `BetaManagedAgentsAgentToolset20260401Params = object { type, configs, default_config }` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` + + Per-tool configuration overrides. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Always Allow Policy + +- `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + +### Beta Managed Agents Always Ask Policy + +- `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Anthropic Skill + +- `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + +### Beta Managed Agents Anthropic Skill Params + +- `BetaManagedAgentsAnthropicSkillParams = object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + +### Beta Managed Agents Custom Skill Params + +- `BetaManagedAgentsCustomSkillParams = object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + +### Beta Managed Agents Custom Tool Input Schema + +- `BetaManagedAgentsCustomToolInputSchema = object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + +### Beta Managed Agents Custom Tool Params + +- `BetaManagedAgentsCustomToolParams = object { description, input_schema, name, type }` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + +### Beta Managed Agents MCP Server URL Definition + +- `BetaManagedAgentsMCPServerURLDefinition = object { name, type, url }` + + URL-based MCP server connection as returned in API responses. + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + +### Beta Managed Agents MCP Tool Config + +- `BetaManagedAgentsMCPToolConfig = object { enabled, name, permission_policy }` + + Resolved configuration for a specific MCP tool. + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Tool Config Params + +- `BetaManagedAgentsMCPToolConfigParams = object { name, enabled, permission_policy }` + + Configuration override for a specific MCP tool. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset + +- `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + +### Beta Managed Agents MCP Toolset Default Config + +- `BetaManagedAgentsMCPToolsetDefaultConfig = object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `BetaManagedAgentsMCPToolsetDefaultConfigParams = object { enabled, permission_policy }` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Params + +- `BetaManagedAgentsMCPToolsetParams = object { mcp_server_name, type, configs, default_config }` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Model + +- `BetaManagedAgentsModel = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + +### Beta Managed Agents Model Config + +- `BetaManagedAgentsModelConfig = object { id, speed }` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Model Config Params + +- `BetaManagedAgentsModelConfigParams = object { id, speed }` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Skill Params + +- `BetaManagedAgentsSkillParams = BetaManagedAgentsAnthropicSkillParams or BetaManagedAgentsCustomSkillParams` + + Skill to load in the session container. + + - `BetaManagedAgentsAnthropicSkillParams = object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams = object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `BetaManagedAgentsURLMCPServerParams = object { name, type, url }` + + URL-based MCP server connection. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + +# Versions + +## List + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Path Parameters + +- `agent_id: string` + +### Query Parameters + +- `limit: optional number` + + Maximum results per page. Default 20, maximum 100. + +- `page: optional string` + + Opaque pagination cursor. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsAgent` + + Agent versions. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID/versions \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +# Environments + +## Create + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Body Parameters + +- `name: string` + + Human-readable name for the environment + +- `config: optional BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams = object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + + - `packages: optional BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +- `description: optional string` + + Optional description of the environment + +- `metadata: optional map[string]` + + User-provided metadata key-value pairs + +### Returns + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```http +curl https://api.anthropic.com/v1/environments \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "name": "python-data-analysis", + "config": { + "type": "cloud", + "networking": { + "type": "limited", + "allow_package_managers": true, + "allowed_hosts": [ + "api.example.com" + ] + }, + "packages": { + "pip": [ + "pandas", + "numpy" + ] + } + } + }' +``` + +## List + +**get** `/v1/environments` + +List environments with pagination support. + +### Query Parameters + +- `include_archived: optional boolean` + + Include archived environments in the response + +- `limit: optional number` + + Maximum number of environments to return + +- `page: optional string` + + Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Returns + +- `data: array of BetaEnvironment` + + List of environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +- `next_page: string` + + Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request. + +### Example + +```http +curl https://api.anthropic.com/v1/environments \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Path Parameters + +- `environment_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Returns + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```http +curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Path Parameters + +- `environment_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Body Parameters + +- `config: optional BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams = object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + + - `packages: optional BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +- `description: optional string` + + Updated description of the environment + +- `metadata: optional map[string]` + + User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + +- `name: optional string` + + Updated name for the environment + +### Returns + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```http +curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "config": { + "type": "cloud", + "networking": { + "type": "limited", + "allow_package_managers": true, + "allowed_hosts": [ + "api.example.com" + ] + }, + "packages": { + "pip": [ + "pandas", + "numpy" + ] + } + } + }' +``` + +## Delete + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Path Parameters + +- `environment_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Returns + +- `BetaEnvironmentDeleteResponse = object { id, type }` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + + - `"environment_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Archive + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Path Parameters + +- `environment_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Returns + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```http +curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Cloud Config + +- `BetaCloudConfig = object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + +### Beta Cloud Config Params + +- `BetaCloudConfigParams = object { type, networking, packages }` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams = object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + + - `packages: optional BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +### Beta Environment + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `BetaEnvironmentDeleteResponse = object { id, type }` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + + - `"environment_deleted"` + +### Beta Limited Network + +- `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + +### Beta Limited Network Params + +- `BetaLimitedNetworkParams = object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + +### Beta Packages + +- `BetaPackages = object { apt, cargo, gem, 4 more }` + + Packages (and their versions) available in this environment. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +### Beta Packages Params + +- `BetaPackagesParams = object { apt, cargo, gem, 4 more }` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +### Beta Unrestricted Network + +- `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + +# Sessions + +## Create + +**post** `/v1/sessions` + +Create Session + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `agent: string or BetaManagedAgentsAgentParams` + + Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `UnionMember0 = string` + + - `BetaManagedAgentsAgentParams = object { id, type, version }` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: string` + + The `agent` ID. + + - `type: "agent"` + + - `"agent"` + + - `version: optional number` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +- `environment_id: string` + + ID of the `environment` defining the container configuration for this session. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata attached to the session. + +- `resources: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams` + + Resources (e.g. repositories, files) to mount into the session's container. + + - `BetaManagedAgentsGitHubRepositoryResourceParams = object { authorization_token, type, url, 2 more }` + + Mount a GitHub repository into the session's container. + + - `authorization_token: string` + + GitHub authorization token used to clone the repository. + + - `type: "github_repository"` + + - `"github_repository"` + + - `url: string` + + Github URL of the repository + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/workspace/`. + + - `BetaManagedAgentsFileResourceParams = object { file_id, type, mount_path }` + + Mount a file uploaded via the Files API into the session. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `title: optional string` + + Human-readable session title. + +- `vault_ids: optional array of string` + + Vault IDs for stored credentials the agent can use during the session. + +### Returns + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "agent": "agent_011CZkYpogX7uDKUyvBTophP", + "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW" + }' +``` + +## List + +**get** `/v1/sessions` + +List Sessions + +### Query Parameters + +- `agent_id: optional string` + + Filter sessions created with this agent ID. + +- `agent_version: optional number` + + Filter by agent version. Only applies when agent_id is also set. + +- `"created_at[gt]": optional string` + + Return sessions created after this time (exclusive). + +- `"created_at[gte]": optional string` + + Return sessions created at or after this time (inclusive). + +- `"created_at[lt]": optional string` + + Return sessions created before this time (exclusive). + +- `"created_at[lte]": optional string` + + Return sessions created at or before this time (inclusive). + +- `include_archived: optional boolean` + + When true, includes archived sessions. Default: false (exclude archived). + +- `limit: optional number` + + Maximum number of results to return. + +- `order: optional "asc" or "desc"` + + Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `"asc"` + + - `"desc"` + +- `page: optional string` + + Opaque pagination cursor from a previous response's next_page. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsSession` + + List of sessions. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + +- `title: optional string` + + Human-readable session title. + +- `vault_ids: optional array of string` + + Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +### Returns + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{}' +``` + +## Delete + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedSession = object { id, type }` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Archive + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `BetaManagedAgentsAgentParams = object { id, type, version }` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: string` + + The `agent` ID. + + - `type: "agent"` + + - `"agent"` + + - `version: optional number` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + +### Beta Managed Agents Cache Creation Usage + +- `BetaManagedAgentsCacheCreationUsage = object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Deleted Session + +- `BetaManagedAgentsDeletedSession = object { id, type }` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Beta Managed Agents File Resource Params + +- `BetaManagedAgentsFileResourceParams = object { file_id, type, mount_path }` + + Mount a file uploaded via the Files API into the session. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `BetaManagedAgentsGitHubRepositoryResourceParams = object { authorization_token, type, url, 2 more }` + + Mount a GitHub repository into the session's container. + + - `authorization_token: string` + + GitHub authorization token used to clone the repository. + + - `type: "github_repository"` + + - `"github_repository"` + + - `url: string` + + Github URL of the repository + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `BetaManagedAgentsSessionAgent = object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + +### Beta Managed Agents Session Stats + +- `BetaManagedAgentsSessionStats = object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `BetaManagedAgentsSessionUsage = object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + +# Events + +## List + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Path Parameters + +- `session_id: string` + +### Query Parameters + +- `limit: optional number` + + Query parameter for limit + +- `order: optional "asc" or "desc"` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"` + + - `"desc"` + +- `page: optional string` + + Opaque pagination cursor from a previous response's next_page. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsSessionEvent` + + Events for the session, ordered by `created_at`. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Send + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `events: array of BetaManagedAgentsEventParams` + + Events to send to the `session`. + + - `BetaManagedAgentsUserMessageEventParams = object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams = object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams = object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams = object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Returns + +- `BetaManagedAgentsSendSessionEvents = object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "events": [ + { + "content": [ + { + "text": "Where is my order #1234?", + "type": "text" + } + ], + "type": "user.message" + } + ] + }' +``` + +## Stream + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Agent Message Event + +- `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Base64 Document Source + +- `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Base64 Image Source + +- `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Billing Error + +- `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + +### Beta Managed Agents Document Block + +- `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + +### Beta Managed Agents Event Params + +- `BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserInterruptEventParams or BetaManagedAgentsUserToolConfirmationEventParams or BetaManagedAgentsUserCustomToolResultEventParams` + + Union type for event parameters that can be sent to a session. + + - `BetaManagedAgentsUserMessageEventParams = object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams = object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams = object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams = object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents File Image Source + +- `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents Image Block + +- `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Retry Status Exhausted + +- `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + +### Beta Managed Agents Send Session Events + +- `BetaManagedAgentsSendSessionEvents = object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + +### Beta Managed Agents Session Error Event + +- `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + +### Beta Managed Agents Session Event + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Union type for all event types in a session. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `BetaManagedAgentsSpanModelUsage = object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Stream Session Events + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Text Block + +- `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Unknown Error + +- `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + +### Beta Managed Agents URL Document Source + +- `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `BetaManagedAgentsUserCustomToolResultEventParams = object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `BetaManagedAgentsUserInterruptEventParams = object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `BetaManagedAgentsUserMessageEventParams = object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `BetaManagedAgentsUserToolConfirmationEventParams = object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `file_id: string` + + ID of a previously uploaded file. + +- `type: "file"` + + - `"file"` + +- `mount_path: optional string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Returns + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", + "type": "file" + }' +``` + +## List + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Path Parameters + +- `session_id: string` + +### Query Parameters + +- `limit: optional number` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `page: optional string` + + Opaque cursor from a previous response's next_page field. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: array of BetaManagedAgentsSessionResource` + + Resources for the session, ordered by `created_at`. + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Path Parameters + +- `session_id: string` + +- `resource_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Path Parameters + +- `session_id: string` + +- `resource_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `authorization_token: string` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +### Returns + +- `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "authorization_token": "ghp_exampletoken" + }' +``` + +## Delete + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Path Parameters + +- `session_id: string` + +- `resource_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeleteSessionResource = object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `BetaManagedAgentsDeleteSessionResource = object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Session Resource + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Resource Retrieve Response + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The requested session resource. + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Resource Update Response + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The updated session resource. + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +# Vaults + +## Create + +**post** `/v1/vaults` + +Create Vault + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `display_name: string` + + Human-readable name for the vault. 1-255 characters. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata to attach to the vault. + +### Returns + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/vaults \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "display_name": "Example vault" + }' +``` + +## List + +**get** `/v1/vaults` + +List Vaults + +### Query Parameters + +- `include_archived: optional boolean` + + Whether to include archived vaults in the results. + +- `limit: optional number` + + Maximum number of vaults to return per page. Defaults to 20, maximum 100. + +- `page: optional string` + + Opaque pagination token from a previous `list_vaults` response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsVault` + + List of vaults. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +- `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `display_name: optional string` + + Updated human-readable name for the vault. 1-255 characters. + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +### Returns + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{}' +``` + +## Delete + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedVault = object { id, type }` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Archive + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `BetaManagedAgentsDeletedVault = object { id, type }` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Beta Managed Agents Vault + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `auth: BetaManagedAgentsMCPOAuthCreateParams or BetaManagedAgentsStaticBearerCreateParams` + + Authentication details for creating a credential. + + - `BetaManagedAgentsMCPOAuthCreateParams = object { access_token, mcp_server_url, type, 2 more }` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerCreateParams = object { token, mcp_server_url, type }` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +- `display_name: optional string` + + Human-readable name for the credential. Up to 255 characters. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata to attach to the credential. + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "auth": { + "token": "bearer_exampletoken", + "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", + "type": "static_bearer" + } + }' +``` + +## List + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Path Parameters + +- `vault_id: string` + +### Query Parameters + +- `include_archived: optional boolean` + + Whether to include archived credentials in the results. + +- `limit: optional number` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `page: optional string` + + Opaque pagination token from a previous `list_credentials` response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsCredential` + + List of credentials. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +- `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `auth: optional BetaManagedAgentsMCPOAuthUpdateParams or BetaManagedAgentsStaticBearerUpdateParams` + + Updated authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthUpdateParams = object { type, access_token, expires_at, refresh }` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token: optional string` + + Updated OAuth access token. + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsStaticBearerUpdateParams = object { type, token }` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token: optional string` + + Updated static bearer token value. + +- `display_name: optional string` + + Updated human-readable name for the credential. 1-255 characters. + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{}' +``` + +## Delete + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedCredential = object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Archive + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` - Exceptional model for specialized complex tasks + - `"prompt-caching-2024-07-31"` - - `"claude-opus-4-1-20250805"` + - `"computer-use-2024-10-22"` - Exceptional model for specialized complex tasks + - `"computer-use-2025-01-24"` - - `"claude-opus-4-0"` + - `"pdfs-2024-09-25"` - Powerful model for complex tasks + - `"token-counting-2024-11-01"` - - `"claude-opus-4-20250514"` + - `"token-efficient-tools-2025-02-19"` - Powerful model for complex tasks + - `"output-128k-2025-02-19"` - - `"claude-sonnet-4-0"` + - `"files-api-2025-04-14"` - High-performance model with extended thinking + - `"mcp-client-2025-04-04"` - - `"claude-sonnet-4-20250514"` + - `"mcp-client-2025-11-20"` - High-performance model with extended thinking + - `"dev-full-thinking-2025-05-14"` - - `"claude-3-haiku-20240307"` + - `"interleaved-thinking-2025-05-14"` - Fast and cost-effective model + - `"code-execution-2025-05-22"` - - `UnionMember1 = string` + - `"extended-cache-ttl-2025-04-11"` - - `role: "assistant"` + - `"context-1m-2025-08-07"` - Conversational role of the generated message. + - `"context-management-2025-06-27"` - This will always be `"assistant"`. + - `"model-context-window-exceeded-2025-08-26"` - - `"assistant"` + - `"skills-2025-10-02"` - - `stop_details: BetaRefusalStopDetails` + - `"fast-mode-2026-02-01"` - Structured information about a refusal. + - `"output-300k-2026-03-24"` - - `category: "cyber" or "bio"` +### Returns - The policy category that triggered the refusal. +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` - `null` when the refusal doesn't map to a named category. + A credential stored in a vault. Sensitive fields are never returned in responses. - - `"cyber"` + - `id: string` - - `"bio"` + Unique identifier for the credential. - - `explanation: string` + - `archived_at: string` - Human-readable explanation of the refusal. + A timestamp in RFC 3339 format - This text is not guaranteed to be stable. `null` when no explanation is available for the category. + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` - - `type: "refusal"` + Authentication details for a credential. - - `"refusal"` + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` - - `stop_reason: BetaStopReason` + OAuth credential details for an MCP server. - The reason that we stopped. + - `mcp_server_url: string` - This may be one the following values: + URL of the MCP server this credential authenticates against. - * `"end_turn"`: the model reached a natural stopping point - * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - * `"tool_use"`: the model invoked one or more tools - * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + - `type: "mcp_oauth"` - In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + - `"mcp_oauth"` - - `"end_turn"` + - `expires_at: optional string` - - `"max_tokens"` + A timestamp in RFC 3339 format - - `"stop_sequence"` + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` - - `"tool_use"` + OAuth refresh token configuration returned in credential responses. - - `"pause_turn"` + - `client_id: string` - - `"compaction"` + OAuth client ID. - - `"refusal"` + - `token_endpoint: string` - - `"model_context_window_exceeded"` + Token endpoint URL used to refresh the access token. - - `stop_sequence: string` + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` - Which custom stop sequence was generated, if any. + Token endpoint requires no client authentication. - This value will be a non-null string if one of your custom stop sequences was generated. + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` - - `type: "message"` + Token endpoint requires no client authentication. - Object type. + - `type: "none"` - For Messages, this is always `"message"`. + - `"none"` - - `"message"` + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` - - `usage: BetaUsage` + Token endpoint uses HTTP Basic authentication with client credentials. - Billing and rate-limit usage. + - `type: "client_secret_basic"` - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + - `"client_secret_basic"` - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + Token endpoint uses POST body authentication with client credentials. - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + - `type: "client_secret_post"` - - `cache_creation: BetaCacheCreation` + - `"client_secret_post"` - Breakdown of cached tokens by TTL + - `resource: optional string` - - `ephemeral_1h_input_tokens: number` + OAuth resource indicator. - The number of input tokens used to create the 1 hour cache entry. + - `scope: optional string` - - `ephemeral_5m_input_tokens: number` + OAuth scope for the refresh request. - The number of input tokens used to create the 5 minute cache entry. + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` - - `cache_creation_input_tokens: number` + Static bearer token credential details for an MCP server. - The number of input tokens used to create the cache entry. + - `mcp_server_url: string` - - `cache_read_input_tokens: number` + URL of the MCP server this credential authenticates against. - The number of input tokens read from the cache. + - `type: "static_bearer"` - - `inference_geo: string` + - `"static_bearer"` - The geographic region where inference was performed for this request. + - `created_at: string` - - `input_tokens: number` + A timestamp in RFC 3339 format - The number of input tokens which were used. + - `metadata: map[string]` - - `iterations: BetaIterationsUsage` + Arbitrary key-value metadata attached to the credential. - Per-iteration token usage breakdown. + - `type: "vault_credential"` - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + - `"vault_credential"` - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops + - `updated_at: string` - - `BetaMessageIterationUsage = object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + A timestamp in RFC 3339 format - Token usage for a sampling iteration. + - `vault_id: string` - - `cache_creation: BetaCacheCreation` + Identifier of the vault this credential belongs to. - Breakdown of cached tokens by TTL + - `display_name: optional string` - - `ephemeral_1h_input_tokens: number` + Human-readable name for the credential. - The number of input tokens used to create the 1 hour cache entry. +### Example - - `ephemeral_5m_input_tokens: number` +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` - The number of input tokens used to create the 5 minute cache entry. +## Domain Types - - `cache_creation_input_tokens: number` +### Beta Managed Agents Credential - The number of input tokens used to create the cache entry. +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` - - `cache_read_input_tokens: number` + A credential stored in a vault. Sensitive fields are never returned in responses. - The number of input tokens read from the cache. + - `id: string` - - `input_tokens: number` + Unique identifier for the credential. - The number of input tokens which were used. + - `archived_at: string` - - `output_tokens: number` + A timestamp in RFC 3339 format - The number of output tokens which were used. + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` - - `type: "message"` + Authentication details for a credential. - Usage for a sampling iteration + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` - - `"message"` + OAuth credential details for an MCP server. - - `BetaCompactionIterationUsage = object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + - `mcp_server_url: string` - Token usage for a compaction iteration. + URL of the MCP server this credential authenticates against. - - `cache_creation: BetaCacheCreation` + - `type: "mcp_oauth"` - Breakdown of cached tokens by TTL + - `"mcp_oauth"` - - `ephemeral_1h_input_tokens: number` + - `expires_at: optional string` - The number of input tokens used to create the 1 hour cache entry. + A timestamp in RFC 3339 format - - `ephemeral_5m_input_tokens: number` + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` - The number of input tokens used to create the 5 minute cache entry. + OAuth refresh token configuration returned in credential responses. - - `cache_creation_input_tokens: number` + - `client_id: string` - The number of input tokens used to create the cache entry. + OAuth client ID. - - `cache_read_input_tokens: number` + - `token_endpoint: string` - The number of input tokens read from the cache. + Token endpoint URL used to refresh the access token. - - `input_tokens: number` + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` - The number of input tokens which were used. + Token endpoint requires no client authentication. - - `output_tokens: number` + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` - The number of output tokens which were used. + Token endpoint requires no client authentication. - - `type: "compaction"` + - `type: "none"` - Usage for a compaction iteration + - `"none"` - - `"compaction"` + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` - - `output_tokens: number` + Token endpoint uses HTTP Basic authentication with client credentials. - The number of output tokens which were used. + - `type: "client_secret_basic"` - - `server_tool_use: BetaServerToolUsage` + - `"client_secret_basic"` - The number of server tool requests. + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` - - `web_fetch_requests: number` + Token endpoint uses POST body authentication with client credentials. - The number of web fetch tool requests. + - `type: "client_secret_post"` - - `web_search_requests: number` + - `"client_secret_post"` - The number of web search tool requests. + - `resource: optional string` - - `service_tier: "standard" or "priority" or "batch"` + OAuth resource indicator. - If the request used the priority, standard, or batch tier. + - `scope: optional string` - - `"standard"` + OAuth scope for the refresh request. - - `"priority"` + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` - - `"batch"` + Static bearer token credential details for an MCP server. - - `speed: "standard" or "fast"` + - `mcp_server_url: string` - The inference speed mode used for this request. + URL of the MCP server this credential authenticates against. - - `"standard"` + - `type: "static_bearer"` - - `"fast"` + - `"static_bearer"` - - `type: "succeeded"` + - `created_at: string` - - `"succeeded"` + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `BetaManagedAgentsDeletedCredential = object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `BetaManagedAgentsMCPOAuthCreateParams = object { access_token, mcp_server_url, type, 2 more }` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `BetaManagedAgentsMCPOAuthRefreshParams = object { client_id, refresh_token, token_endpoint, 3 more }` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `BetaManagedAgentsMCPOAuthRefreshResponse = object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `BetaManagedAgentsMCPOAuthRefreshUpdateParams = object { refresh_token, scope, token_endpoint_auth }` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `BetaManagedAgentsMCPOAuthUpdateParams = object { type, access_token, expires_at, refresh }` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token: optional string` + + Updated OAuth access token. + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `BetaManagedAgentsStaticBearerCreateParams = object { token, mcp_server_url, type }` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `BetaManagedAgentsStaticBearerUpdateParams = object { type, token }` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token: optional string` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. # Files @@ -45366,7 +68255,7 @@ Upload File - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -45410,11 +68299,9 @@ Upload File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns -- `FileMetadata = object { id, created_at, filename, 4 more }` +- `FileMetadata = object { id, created_at, filename, 5 more }` - `id: string` @@ -45450,6 +68337,20 @@ Upload File Whether the file can be downloaded. + - `scope: optional BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```http @@ -45483,6 +68384,10 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. +- `scope_id: optional string` + + Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + ### Header Parameters - `"anthropic-beta": optional array of AnthropicBeta` @@ -45491,7 +68396,7 @@ List Files - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -45535,8 +68440,6 @@ List Files - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of FileMetadata` @@ -45577,6 +68480,20 @@ List Files Whether the file can be downloaded. + - `scope: optional BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + - `first_id: optional string` ID of the first file in this page of results. @@ -45618,7 +68535,7 @@ Download File - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -45662,8 +68579,6 @@ Download File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Example ```http @@ -45693,7 +68608,7 @@ Get File Metadata - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -45737,11 +68652,9 @@ Get File Metadata - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns -- `FileMetadata = object { id, created_at, filename, 4 more }` +- `FileMetadata = object { id, created_at, filename, 5 more }` - `id: string` @@ -45777,6 +68690,20 @@ Get File Metadata Whether the file can be downloaded. + - `scope: optional BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```http @@ -45806,7 +68733,7 @@ Delete File - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -45850,8 +68777,6 @@ Delete File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `DeletedFile = object { id, type }` @@ -45880,6 +68805,20 @@ curl https://api.anthropic.com/v1/files/$FILE_ID \ ## Domain Types +### Beta File Scope + +- `BetaFileScope = object { id, type }` + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Deleted File - `DeletedFile = object { id, type }` @@ -45898,7 +68837,7 @@ curl https://api.anthropic.com/v1/files/$FILE_ID \ ### File Metadata -- `FileMetadata = object { id, created_at, filename, 4 more }` +- `FileMetadata = object { id, created_at, filename, 5 more }` - `id: string` @@ -45934,6 +68873,20 @@ curl https://api.anthropic.com/v1/files/$FILE_ID \ Whether the file can be downloaded. + - `scope: optional BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + # Skills ## Create @@ -45950,7 +68903,7 @@ Create Skill - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -45994,8 +68947,6 @@ Create Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -46086,7 +69037,7 @@ List Skills - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -46130,8 +69081,6 @@ List Skills - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of object { id, created_at, display_title, 4 more }` @@ -46222,7 +69171,7 @@ Get Skill - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -46266,8 +69215,6 @@ Get Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -46342,7 +69289,7 @@ Delete Skill - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -46386,8 +69333,6 @@ Delete Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -46589,7 +69534,7 @@ Create Skill Version - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -46633,8 +69578,6 @@ Create Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -46725,7 +69668,7 @@ List Skill Versions - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -46769,8 +69712,6 @@ List Skill Versions - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of object { id, created_at, description, 5 more }` @@ -46866,7 +69807,7 @@ Get Skill Version - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -46910,8 +69851,6 @@ Get Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -46995,7 +69934,7 @@ Delete Skill Version - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -47039,8 +69978,6 @@ Delete Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -47226,555 +70163,3 @@ curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \ Deleted object type. For Skill Versions, this is always `"skill_version_deleted"`. - -# User Profiles - -## Create - -**post** `/v1/user_profiles` - -Create User Profile - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Body Parameters - -- `external_id: optional string` - -- `metadata: optional map[string]` - - Free-form key-value data to attach to this user profile. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. Values must be non-empty strings. - -### Returns - -- `BetaUserProfile = object { id, created_at, metadata, 4 more }` - - - `id: string` - - - `created_at: string` - - A timestamp in RFC 3339 format - - - `metadata: map[string]` - - - `trust_grants: map[BetaUserProfileTrustGrant]` - - - `status: string` - - - `type: string` - - - `updated_at: string` - - A timestamp in RFC 3339 format - - - `external_id: optional string` - -### Example - -```http -curl https://api.anthropic.com/v1/user_profiles \ - -H 'Content-Type: application/json' \ - -H 'anthropic-version: 2023-06-01' \ - -H 'anthropic-beta: user-profiles-2026-03-24' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" \ - -d '{}' -``` - -## List - -**get** `/v1/user_profiles` - -List User Profiles - -### Query Parameters - -- `limit: optional number` - - Query parameter for limit - -- `order: optional "asc" or "desc"` - - Query parameter for order - - - `"asc"` - - - `"desc"` - -- `page: optional string` - - Query parameter for page - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `data: array of BetaUserProfile` - - - `id: string` - - - `created_at: string` - - A timestamp in RFC 3339 format - - - `metadata: map[string]` - - - `trust_grants: map[BetaUserProfileTrustGrant]` - - - `status: string` - - - `type: string` - - - `updated_at: string` - - A timestamp in RFC 3339 format - - - `external_id: optional string` - -- `next_page: optional string` - -### Example - -```http -curl https://api.anthropic.com/v1/user_profiles \ - -H 'anthropic-version: 2023-06-01' \ - -H 'anthropic-beta: user-profiles-2026-03-24' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" -``` - -## Retrieve - -**get** `/v1/user_profiles/{id}` - -Get User Profile - -### Path Parameters - -- `id: string` - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `BetaUserProfile = object { id, created_at, metadata, 4 more }` - - - `id: string` - - - `created_at: string` - - A timestamp in RFC 3339 format - - - `metadata: map[string]` - - - `trust_grants: map[BetaUserProfileTrustGrant]` - - - `status: string` - - - `type: string` - - - `updated_at: string` - - A timestamp in RFC 3339 format - - - `external_id: optional string` - -### Example - -```http -curl https://api.anthropic.com/v1/user_profiles/$ID \ - -H 'anthropic-version: 2023-06-01' \ - -H 'anthropic-beta: user-profiles-2026-03-24' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" -``` - -## Update - -**post** `/v1/user_profiles/{id}` - -Update User Profile - -### Path Parameters - -- `id: string` - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Body Parameters - -- `external_id: optional string` - -- `metadata: optional map[string]` - - Key-value pairs to merge into the stored metadata. Keys provided overwrite existing values. To remove a key, set its value to an empty string. Keys not provided are left unchanged. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. - -### Returns - -- `BetaUserProfile = object { id, created_at, metadata, 4 more }` - - - `id: string` - - - `created_at: string` - - A timestamp in RFC 3339 format - - - `metadata: map[string]` - - - `trust_grants: map[BetaUserProfileTrustGrant]` - - - `status: string` - - - `type: string` - - - `updated_at: string` - - A timestamp in RFC 3339 format - - - `external_id: optional string` - -### Example - -```http -curl https://api.anthropic.com/v1/user_profiles/$ID \ - -H 'Content-Type: application/json' \ - -H 'anthropic-version: 2023-06-01' \ - -H 'anthropic-beta: user-profiles-2026-03-24' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" \ - -d '{}' -``` - -## Create Enrollment URL - -**post** `/v1/user_profiles/{id}/enrollment_url` - -Create Enrollment URL - -### Path Parameters - -- `id: string` - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `BetaUserProfileEnrollmentURL = object { expires_at, type, url }` - - - `expires_at: string` - - A timestamp in RFC 3339 format - - - `type: string` - - - `url: string` - -### Example - -```http -curl https://api.anthropic.com/v1/user_profiles/$ID/enrollment_url \ - -X POST \ - -H 'anthropic-version: 2023-06-01' \ - -H 'anthropic-beta: user-profiles-2026-03-24' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" -``` - -## Domain Types - -### Beta User Profile - -- `BetaUserProfile = object { id, created_at, metadata, 4 more }` - - - `id: string` - - - `created_at: string` - - A timestamp in RFC 3339 format - - - `metadata: map[string]` - - - `trust_grants: map[BetaUserProfileTrustGrant]` - - - `status: string` - - - `type: string` - - - `updated_at: string` - - A timestamp in RFC 3339 format - - - `external_id: optional string` - -### Beta User Profile Enrollment URL - -- `BetaUserProfileEnrollmentURL = object { expires_at, type, url }` - - - `expires_at: string` - - A timestamp in RFC 3339 format - - - `type: string` - - - `url: string` - -### Beta User Profile Trust Grant - -- `BetaUserProfileTrustGrant = object { status }` - - - `status: string` diff --git a/content/en/api/beta/agents.md b/content/en/api/beta/agents.md new file mode 100644 index 000000000..38e438d41 --- /dev/null +++ b/content/en/api/beta/agents.md @@ -0,0 +1,4301 @@ +# Agents + +## Create + +**post** `/v1/agents` + +Create Agent + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `model: BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `BetaManagedAgentsModel = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `BetaManagedAgentsModelConfigParams = object { id, speed }` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +- `name: string` + + Human-readable name for the agent. 1-256 characters. + +- `description: optional string` + + Description of what the agent does. Up to 2048 characters. + +- `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams` + + MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + +- `skills: optional array of BetaManagedAgentsSkillParams` + + Skills available to the agent. Maximum 20. + + - `BetaManagedAgentsAnthropicSkillParams = object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams = object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +- `system: optional string` + + System prompt for the agent. Up to 100,000 characters. + +- `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` + + Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `BetaManagedAgentsAgentToolset20260401Params = object { type, configs, default_config }` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` + + Per-tool configuration overrides. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsMCPToolsetParams = object { mcp_server_name, type, configs, default_config }` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsCustomToolParams = object { description, input_schema, name, type }` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + +### Returns + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```http +curl https://api.anthropic.com/v1/agents \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "model": "claude-sonnet-4-6", + "name": "My First Agent" + }' +``` + +## List + +**get** `/v1/agents` + +List Agents + +### Query Parameters + +- `"created_at[gte]": optional string` + + Return agents created at or after this time (inclusive). + +- `"created_at[lte]": optional string` + + Return agents created at or before this time (inclusive). + +- `include_archived: optional boolean` + + Include archived agents in results. Defaults to false. + +- `limit: optional number` + + Maximum results per page. Default 20, maximum 100. + +- `page: optional string` + + Opaque pagination cursor from a previous response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsAgent` + + List of agents. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/agents \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Path Parameters + +- `agent_id: string` + +### Query Parameters + +- `version: optional number` + + Agent version. Omit for the most recent version. Must be at least 1 if specified. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Path Parameters + +- `agent_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `version: number` + + The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + +- `description: optional string` + + Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + +- `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams` + + MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + +- `model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `BetaManagedAgentsModel = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `BetaManagedAgentsModelConfigParams = object { id, speed }` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +- `name: optional string` + + Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + +- `skills: optional array of BetaManagedAgentsSkillParams` + + Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `BetaManagedAgentsAnthropicSkillParams = object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams = object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +- `system: optional string` + + System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + +- `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` + + Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `BetaManagedAgentsAgentToolset20260401Params = object { type, configs, default_config }` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` + + Per-tool configuration overrides. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsMCPToolsetParams = object { mcp_server_name, type, configs, default_config }` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsCustomToolParams = object { description, input_schema, name, type }` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + +### Returns + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "version": 1 + }' +``` + +## Archive + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Path Parameters + +- `agent_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `BetaManagedAgentsAgentToolConfig = object { enabled, name, permission_policy }` + + Configuration for a specific agent tool. + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Tool Config Params + +- `BetaManagedAgentsAgentToolConfigParams = object { name, enabled, permission_policy }` + + Configuration override for a specific tool within a toolset. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config + +- `BetaManagedAgentsAgentToolsetDefaultConfig = object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `BetaManagedAgentsAgentToolsetDefaultConfigParams = object { enabled, permission_policy }` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset20260401 + +- `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `BetaManagedAgentsAgentToolset20260401Params = object { type, configs, default_config }` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` + + Per-tool configuration overrides. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Always Allow Policy + +- `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + +### Beta Managed Agents Always Ask Policy + +- `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Anthropic Skill + +- `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + +### Beta Managed Agents Anthropic Skill Params + +- `BetaManagedAgentsAnthropicSkillParams = object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + +### Beta Managed Agents Custom Skill Params + +- `BetaManagedAgentsCustomSkillParams = object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + +### Beta Managed Agents Custom Tool Input Schema + +- `BetaManagedAgentsCustomToolInputSchema = object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + +### Beta Managed Agents Custom Tool Params + +- `BetaManagedAgentsCustomToolParams = object { description, input_schema, name, type }` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + +### Beta Managed Agents MCP Server URL Definition + +- `BetaManagedAgentsMCPServerURLDefinition = object { name, type, url }` + + URL-based MCP server connection as returned in API responses. + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + +### Beta Managed Agents MCP Tool Config + +- `BetaManagedAgentsMCPToolConfig = object { enabled, name, permission_policy }` + + Resolved configuration for a specific MCP tool. + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Tool Config Params + +- `BetaManagedAgentsMCPToolConfigParams = object { name, enabled, permission_policy }` + + Configuration override for a specific MCP tool. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset + +- `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + +### Beta Managed Agents MCP Toolset Default Config + +- `BetaManagedAgentsMCPToolsetDefaultConfig = object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `BetaManagedAgentsMCPToolsetDefaultConfigParams = object { enabled, permission_policy }` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Params + +- `BetaManagedAgentsMCPToolsetParams = object { mcp_server_name, type, configs, default_config }` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Model + +- `BetaManagedAgentsModel = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + +### Beta Managed Agents Model Config + +- `BetaManagedAgentsModelConfig = object { id, speed }` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Model Config Params + +- `BetaManagedAgentsModelConfigParams = object { id, speed }` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Skill Params + +- `BetaManagedAgentsSkillParams = BetaManagedAgentsAnthropicSkillParams or BetaManagedAgentsCustomSkillParams` + + Skill to load in the session container. + + - `BetaManagedAgentsAnthropicSkillParams = object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams = object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `BetaManagedAgentsURLMCPServerParams = object { name, type, url }` + + URL-based MCP server connection. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + +# Versions + +## List + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Path Parameters + +- `agent_id: string` + +### Query Parameters + +- `limit: optional number` + + Maximum results per page. Default 20, maximum 100. + +- `page: optional string` + + Opaque pagination cursor. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsAgent` + + Agent versions. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID/versions \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/agents/archive.md b/content/en/api/beta/agents/archive.md new file mode 100644 index 000000000..6ec30b465 --- /dev/null +++ b/content/en/api/beta/agents/archive.md @@ -0,0 +1,369 @@ +## Archive + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Path Parameters + +- `agent_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/agents/create.md b/content/en/api/beta/agents/create.md new file mode 100644 index 000000000..99baefc92 --- /dev/null +++ b/content/en/api/beta/agents/create.md @@ -0,0 +1,741 @@ +## Create + +**post** `/v1/agents` + +Create Agent + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `model: BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `BetaManagedAgentsModel = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `BetaManagedAgentsModelConfigParams = object { id, speed }` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +- `name: string` + + Human-readable name for the agent. 1-256 characters. + +- `description: optional string` + + Description of what the agent does. Up to 2048 characters. + +- `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams` + + MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + +- `skills: optional array of BetaManagedAgentsSkillParams` + + Skills available to the agent. Maximum 20. + + - `BetaManagedAgentsAnthropicSkillParams = object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams = object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +- `system: optional string` + + System prompt for the agent. Up to 100,000 characters. + +- `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` + + Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `BetaManagedAgentsAgentToolset20260401Params = object { type, configs, default_config }` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` + + Per-tool configuration overrides. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsMCPToolsetParams = object { mcp_server_name, type, configs, default_config }` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsCustomToolParams = object { description, input_schema, name, type }` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + +### Returns + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```http +curl https://api.anthropic.com/v1/agents \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "model": "claude-sonnet-4-6", + "name": "My First Agent" + }' +``` diff --git a/content/en/api/beta/agents/list.md b/content/en/api/beta/agents/list.md new file mode 100644 index 000000000..fa653c48b --- /dev/null +++ b/content/en/api/beta/agents/list.md @@ -0,0 +1,390 @@ +## List + +**get** `/v1/agents` + +List Agents + +### Query Parameters + +- `"created_at[gte]": optional string` + + Return agents created at or after this time (inclusive). + +- `"created_at[lte]": optional string` + + Return agents created at or before this time (inclusive). + +- `include_archived: optional boolean` + + Include archived agents in results. Defaults to false. + +- `limit: optional number` + + Maximum results per page. Default 20, maximum 100. + +- `page: optional string` + + Opaque pagination cursor from a previous response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsAgent` + + List of agents. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/agents \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/agents/retrieve.md b/content/en/api/beta/agents/retrieve.md new file mode 100644 index 000000000..e256d4ff9 --- /dev/null +++ b/content/en/api/beta/agents/retrieve.md @@ -0,0 +1,374 @@ +## Retrieve + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Path Parameters + +- `agent_id: string` + +### Query Parameters + +- `version: optional number` + + Agent version. Omit for the most recent version. Must be at least 1 if specified. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/agents/update.md b/content/en/api/beta/agents/update.md new file mode 100644 index 000000000..7b46129a5 --- /dev/null +++ b/content/en/api/beta/agents/update.md @@ -0,0 +1,748 @@ +## Update + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Path Parameters + +- `agent_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `version: number` + + The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + +- `description: optional string` + + Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + +- `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams` + + MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + +- `model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `BetaManagedAgentsModel = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `BetaManagedAgentsModelConfigParams = object { id, speed }` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +- `name: optional string` + + Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + +- `skills: optional array of BetaManagedAgentsSkillParams` + + Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `BetaManagedAgentsAnthropicSkillParams = object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams = object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +- `system: optional string` + + System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + +- `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` + + Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `BetaManagedAgentsAgentToolset20260401Params = object { type, configs, default_config }` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` + + Per-tool configuration overrides. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsMCPToolsetParams = object { mcp_server_name, type, configs, default_config }` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsCustomToolParams = object { description, input_schema, name, type }` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + +### Returns + +- `BetaManagedAgentsAgent = object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "version": 1 + }' +``` diff --git a/content/en/api/beta/agents/versions.md b/content/en/api/beta/agents/versions.md new file mode 100644 index 000000000..5415ec41c --- /dev/null +++ b/content/en/api/beta/agents/versions.md @@ -0,0 +1,384 @@ +# Versions + +## List + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Path Parameters + +- `agent_id: string` + +### Query Parameters + +- `limit: optional number` + + Maximum results per page. Default 20, maximum 100. + +- `page: optional string` + + Opaque pagination cursor. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsAgent` + + Agent versions. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID/versions \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/agents/versions/list.md b/content/en/api/beta/agents/versions/list.md new file mode 100644 index 000000000..0a5bfa87e --- /dev/null +++ b/content/en/api/beta/agents/versions/list.md @@ -0,0 +1,382 @@ +## List + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Path Parameters + +- `agent_id: string` + +### Query Parameters + +- `limit: optional number` + + Maximum results per page. Default 20, maximum 100. + +- `page: optional string` + + Opaque pagination cursor. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsAgent` + + Agent versions. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/agents/$AGENT_ID/versions \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/environments.md b/content/en/api/beta/environments.md new file mode 100644 index 000000000..0925f4650 --- /dev/null +++ b/content/en/api/beta/environments.md @@ -0,0 +1,1769 @@ +# Environments + +## Create + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Body Parameters + +- `name: string` + + Human-readable name for the environment + +- `config: optional BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams = object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + + - `packages: optional BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +- `description: optional string` + + Optional description of the environment + +- `metadata: optional map[string]` + + User-provided metadata key-value pairs + +### Returns + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```http +curl https://api.anthropic.com/v1/environments \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "name": "python-data-analysis", + "config": { + "type": "cloud", + "networking": { + "type": "limited", + "allow_package_managers": true, + "allowed_hosts": [ + "api.example.com" + ] + }, + "packages": { + "pip": [ + "pandas", + "numpy" + ] + } + } + }' +``` + +## List + +**get** `/v1/environments` + +List environments with pagination support. + +### Query Parameters + +- `include_archived: optional boolean` + + Include archived environments in the response + +- `limit: optional number` + + Maximum number of environments to return + +- `page: optional string` + + Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Returns + +- `data: array of BetaEnvironment` + + List of environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +- `next_page: string` + + Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request. + +### Example + +```http +curl https://api.anthropic.com/v1/environments \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Path Parameters + +- `environment_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Returns + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```http +curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Path Parameters + +- `environment_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Body Parameters + +- `config: optional BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams = object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + + - `packages: optional BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +- `description: optional string` + + Updated description of the environment + +- `metadata: optional map[string]` + + User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + +- `name: optional string` + + Updated name for the environment + +### Returns + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```http +curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "config": { + "type": "cloud", + "networking": { + "type": "limited", + "allow_package_managers": true, + "allowed_hosts": [ + "api.example.com" + ] + }, + "packages": { + "pip": [ + "pandas", + "numpy" + ] + } + } + }' +``` + +## Delete + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Path Parameters + +- `environment_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Returns + +- `BetaEnvironmentDeleteResponse = object { id, type }` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + + - `"environment_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Archive + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Path Parameters + +- `environment_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Returns + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```http +curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Cloud Config + +- `BetaCloudConfig = object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + +### Beta Cloud Config Params + +- `BetaCloudConfigParams = object { type, networking, packages }` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams = object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + + - `packages: optional BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +### Beta Environment + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `BetaEnvironmentDeleteResponse = object { id, type }` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + + - `"environment_deleted"` + +### Beta Limited Network + +- `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + +### Beta Limited Network Params + +- `BetaLimitedNetworkParams = object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + +### Beta Packages + +- `BetaPackages = object { apt, cargo, gem, 4 more }` + + Packages (and their versions) available in this environment. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +### Beta Packages Params + +- `BetaPackagesParams = object { apt, cargo, gem, 4 more }` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +### Beta Unrestricted Network + +- `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` diff --git a/content/en/api/beta/environments/archive.md b/content/en/api/beta/environments/archive.md new file mode 100644 index 000000000..82258aca5 --- /dev/null +++ b/content/en/api/beta/environments/archive.md @@ -0,0 +1,195 @@ +## Archive + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Path Parameters + +- `environment_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Returns + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```http +curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/environments/create.md b/content/en/api/beta/environments/create.md new file mode 100644 index 000000000..2d3b50530 --- /dev/null +++ b/content/en/api/beta/environments/create.md @@ -0,0 +1,312 @@ +## Create + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Body Parameters + +- `name: string` + + Human-readable name for the environment + +- `config: optional BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams = object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + + - `packages: optional BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +- `description: optional string` + + Optional description of the environment + +- `metadata: optional map[string]` + + User-provided metadata key-value pairs + +### Returns + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```http +curl https://api.anthropic.com/v1/environments \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "name": "python-data-analysis", + "config": { + "type": "cloud", + "networking": { + "type": "limited", + "allow_package_managers": true, + "allowed_hosts": [ + "api.example.com" + ] + }, + "packages": { + "pip": [ + "pandas", + "numpy" + ] + } + } + }' +``` diff --git a/content/en/api/beta/environments/delete.md b/content/en/api/beta/environments/delete.md new file mode 100644 index 000000000..cf22d1f4b --- /dev/null +++ b/content/en/api/beta/environments/delete.md @@ -0,0 +1,91 @@ +## Delete + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Path Parameters + +- `environment_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Returns + +- `BetaEnvironmentDeleteResponse = object { id, type }` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + + - `"environment_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/environments/list.md b/content/en/api/beta/environments/list.md new file mode 100644 index 000000000..207f67384 --- /dev/null +++ b/content/en/api/beta/environments/list.md @@ -0,0 +1,208 @@ +## List + +**get** `/v1/environments` + +List environments with pagination support. + +### Query Parameters + +- `include_archived: optional boolean` + + Include archived environments in the response + +- `limit: optional number` + + Maximum number of environments to return + +- `page: optional string` + + Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Returns + +- `data: array of BetaEnvironment` + + List of environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +- `next_page: string` + + Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request. + +### Example + +```http +curl https://api.anthropic.com/v1/environments \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/environments/retrieve.md b/content/en/api/beta/environments/retrieve.md new file mode 100644 index 000000000..90e871208 --- /dev/null +++ b/content/en/api/beta/environments/retrieve.md @@ -0,0 +1,194 @@ +## Retrieve + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Path Parameters + +- `environment_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Returns + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```http +curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/environments/update.md b/content/en/api/beta/environments/update.md new file mode 100644 index 000000000..0542ea35a --- /dev/null +++ b/content/en/api/beta/environments/update.md @@ -0,0 +1,315 @@ +## Update + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Path Parameters + +- `environment_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Cookie Parameters + +- `sessionKey: optional string` + +### Body Parameters + +- `config: optional BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams = object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + + - `packages: optional BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +- `description: optional string` + + Updated description of the environment + +- `metadata: optional map[string]` + + User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + +- `name: optional string` + + Updated name for the environment + +### Returns + +- `BetaEnvironment = object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork = object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork = object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```http +curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "config": { + "type": "cloud", + "networking": { + "type": "limited", + "allow_package_managers": true, + "allowed_hosts": [ + "api.example.com" + ] + }, + "packages": { + "pip": [ + "pandas", + "numpy" + ] + } + } + }' +``` diff --git a/content/en/api/beta/files.md b/content/en/api/beta/files.md index cd40bc85b..0c58eb9e4 100644 --- a/content/en/api/beta/files.md +++ b/content/en/api/beta/files.md @@ -14,7 +14,7 @@ Upload File - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -58,11 +58,9 @@ Upload File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns -- `FileMetadata = object { id, created_at, filename, 4 more }` +- `FileMetadata = object { id, created_at, filename, 5 more }` - `id: string` @@ -98,6 +96,20 @@ Upload File Whether the file can be downloaded. + - `scope: optional BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```http @@ -131,6 +143,10 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. +- `scope_id: optional string` + + Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + ### Header Parameters - `"anthropic-beta": optional array of AnthropicBeta` @@ -139,7 +155,7 @@ List Files - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -183,8 +199,6 @@ List Files - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of FileMetadata` @@ -225,6 +239,20 @@ List Files Whether the file can be downloaded. + - `scope: optional BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + - `first_id: optional string` ID of the first file in this page of results. @@ -266,7 +294,7 @@ Download File - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -310,8 +338,6 @@ Download File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Example ```http @@ -341,7 +367,7 @@ Get File Metadata - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -385,11 +411,9 @@ Get File Metadata - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns -- `FileMetadata = object { id, created_at, filename, 4 more }` +- `FileMetadata = object { id, created_at, filename, 5 more }` - `id: string` @@ -425,6 +449,20 @@ Get File Metadata Whether the file can be downloaded. + - `scope: optional BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```http @@ -454,7 +492,7 @@ Delete File - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -498,8 +536,6 @@ Delete File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `DeletedFile = object { id, type }` @@ -528,6 +564,20 @@ curl https://api.anthropic.com/v1/files/$FILE_ID \ ## Domain Types +### Beta File Scope + +- `BetaFileScope = object { id, type }` + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Deleted File - `DeletedFile = object { id, type }` @@ -546,7 +596,7 @@ curl https://api.anthropic.com/v1/files/$FILE_ID \ ### File Metadata -- `FileMetadata = object { id, created_at, filename, 4 more }` +- `FileMetadata = object { id, created_at, filename, 5 more }` - `id: string` @@ -581,3 +631,17 @@ curl https://api.anthropic.com/v1/files/$FILE_ID \ - `downloadable: optional boolean` Whether the file can be downloaded. + + - `scope: optional BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` diff --git a/content/en/api/beta/files/delete.md b/content/en/api/beta/files/delete.md index 7009deee2..90d03544b 100644 --- a/content/en/api/beta/files/delete.md +++ b/content/en/api/beta/files/delete.md @@ -18,7 +18,7 @@ Delete File - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Delete File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `DeletedFile = object { id, type }` diff --git a/content/en/api/beta/files/download.md b/content/en/api/beta/files/download.md index 8d1164776..0e7a01d9e 100644 --- a/content/en/api/beta/files/download.md +++ b/content/en/api/beta/files/download.md @@ -18,7 +18,7 @@ Download File - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Download File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Example ```http diff --git a/content/en/api/beta/files/list.md b/content/en/api/beta/files/list.md index 8668a0ba0..089a26859 100644 --- a/content/en/api/beta/files/list.md +++ b/content/en/api/beta/files/list.md @@ -20,6 +20,10 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. +- `scope_id: optional string` + + Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + ### Header Parameters - `"anthropic-beta": optional array of AnthropicBeta` @@ -28,7 +32,7 @@ List Files - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -72,8 +76,6 @@ List Files - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of FileMetadata` @@ -114,6 +116,20 @@ List Files Whether the file can be downloaded. + - `scope: optional BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + - `first_id: optional string` ID of the first file in this page of results. diff --git a/content/en/api/beta/files/retrieve_metadata.md b/content/en/api/beta/files/retrieve_metadata.md index 2172981e2..eecc8ac55 100644 --- a/content/en/api/beta/files/retrieve_metadata.md +++ b/content/en/api/beta/files/retrieve_metadata.md @@ -18,7 +18,7 @@ Get File Metadata - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -62,11 +62,9 @@ Get File Metadata - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns -- `FileMetadata = object { id, created_at, filename, 4 more }` +- `FileMetadata = object { id, created_at, filename, 5 more }` - `id: string` @@ -102,6 +100,20 @@ Get File Metadata Whether the file can be downloaded. + - `scope: optional BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```http diff --git a/content/en/api/beta/files/upload.md b/content/en/api/beta/files/upload.md index 47b2d0fc5..fe485bb97 100644 --- a/content/en/api/beta/files/upload.md +++ b/content/en/api/beta/files/upload.md @@ -12,7 +12,7 @@ Upload File - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -56,11 +56,9 @@ Upload File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns -- `FileMetadata = object { id, created_at, filename, 4 more }` +- `FileMetadata = object { id, created_at, filename, 5 more }` - `id: string` @@ -96,6 +94,20 @@ Upload File Whether the file can be downloaded. + - `scope: optional BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```http diff --git a/content/en/api/beta/messages.md b/content/en/api/beta/messages.md index b01a5b1ef..26133cd09 100644 --- a/content/en/api/beta/messages.md +++ b/content/en/api/beta/messages.md @@ -18,7 +18,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Body Parameters - `max_tokens: number` @@ -2651,15 +2649,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4728,10 +4730,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. -- `user_profile_id: optional string` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - ### Returns - `BetaMessage = object { id, container, content, 8 more }` @@ -5655,15 +5653,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -5998,7 +6000,7 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -6042,8 +6044,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Body Parameters - `messages: array of BetaMessageParam` @@ -8623,15 +8623,19 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -10634,7 +10638,7 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ "role": "user" } ], - "model": "claude-opus-4-6" + "model": "claude-mythos-preview" }' ``` @@ -17823,15 +17827,19 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -23167,15 +23175,19 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -24411,15 +24423,19 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -32954,7 +32970,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -32998,8 +33014,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Body Parameters - `requests: array of object { custom_id, params }` @@ -33012,7 +33026,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Must be unique for each request within the Message Batch. - - `params: object { max_tokens, messages, model, 20 more }` + - `params: object { max_tokens, messages, model, 19 more }` Messages API creation parameters for the individual request. @@ -35603,15 +35617,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -37680,10 +37698,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id: optional string` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - ### Returns - `BetaMessageBatch = object { id, archived_at, cancel_initiated_at, 7 more }` @@ -37823,7 +37837,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -37867,8 +37881,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch = object { id, archived_at, cancel_initiated_at, 7 more }` @@ -38000,7 +38012,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -38044,8 +38056,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of BetaMessageBatch` @@ -38181,7 +38191,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -38225,8 +38235,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch = object { id, archived_at, cancel_initiated_at, 7 more }` @@ -38351,7 +38359,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -38395,8 +38403,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaDeletedMessageBatch = object { id, type }` @@ -38447,7 +38453,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -38491,8 +38497,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatchIndividualResponse = object { custom_id, result }` @@ -39434,15 +39438,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -41007,15 +41015,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -42379,15 +42391,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -43713,15 +43729,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/beta/messages/batches.md b/content/en/api/beta/messages/batches.md index 1e6c99d13..8ed89d12d 100644 --- a/content/en/api/beta/messages/batches.md +++ b/content/en/api/beta/messages/batches.md @@ -18,7 +18,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Body Parameters - `requests: array of object { custom_id, params }` @@ -76,7 +74,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Must be unique for each request within the Message Batch. - - `params: object { max_tokens, messages, model, 20 more }` + - `params: object { max_tokens, messages, model, 19 more }` Messages API creation parameters for the individual request. @@ -2667,15 +2665,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4744,10 +4746,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id: optional string` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - ### Returns - `BetaMessageBatch = object { id, archived_at, cancel_initiated_at, 7 more }` @@ -4887,7 +4885,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -4931,8 +4929,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch = object { id, archived_at, cancel_initiated_at, 7 more }` @@ -5064,7 +5060,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -5108,8 +5104,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of BetaMessageBatch` @@ -5245,7 +5239,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -5289,8 +5283,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch = object { id, archived_at, cancel_initiated_at, 7 more }` @@ -5415,7 +5407,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -5459,8 +5451,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaDeletedMessageBatch = object { id, type }` @@ -5511,7 +5501,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -5555,8 +5545,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatchIndividualResponse = object { custom_id, result }` @@ -6498,15 +6486,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -8071,15 +8063,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -9443,15 +9439,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -10777,15 +10777,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/beta/messages/batches/cancel.md b/content/en/api/beta/messages/batches/cancel.md index b637d8c84..a554bb738 100644 --- a/content/en/api/beta/messages/batches/cancel.md +++ b/content/en/api/beta/messages/batches/cancel.md @@ -22,7 +22,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch = object { id, archived_at, cancel_initiated_at, 7 more }` diff --git a/content/en/api/beta/messages/batches/create.md b/content/en/api/beta/messages/batches/create.md index 60945a961..87d0f4794 100644 --- a/content/en/api/beta/messages/batches/create.md +++ b/content/en/api/beta/messages/batches/create.md @@ -16,7 +16,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -60,8 +60,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Body Parameters - `requests: array of object { custom_id, params }` @@ -74,7 +72,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Must be unique for each request within the Message Batch. - - `params: object { max_tokens, messages, model, 20 more }` + - `params: object { max_tokens, messages, model, 19 more }` Messages API creation parameters for the individual request. @@ -2665,15 +2663,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4742,10 +4744,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id: optional string` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - ### Returns - `BetaMessageBatch = object { id, archived_at, cancel_initiated_at, 7 more }` diff --git a/content/en/api/beta/messages/batches/delete.md b/content/en/api/beta/messages/batches/delete.md index b2a0e521a..121ee3398 100644 --- a/content/en/api/beta/messages/batches/delete.md +++ b/content/en/api/beta/messages/batches/delete.md @@ -22,7 +22,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaDeletedMessageBatch = object { id, type }` diff --git a/content/en/api/beta/messages/batches/list.md b/content/en/api/beta/messages/batches/list.md index 602d870bd..227f1c2ca 100644 --- a/content/en/api/beta/messages/batches/list.md +++ b/content/en/api/beta/messages/batches/list.md @@ -30,7 +30,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of BetaMessageBatch` diff --git a/content/en/api/beta/messages/batches/results.md b/content/en/api/beta/messages/batches/results.md index fff5b6b91..c46b3e8ac 100644 --- a/content/en/api/beta/messages/batches/results.md +++ b/content/en/api/beta/messages/batches/results.md @@ -22,7 +22,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatchIndividualResponse = object { custom_id, result }` @@ -1009,15 +1007,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/beta/messages/batches/retrieve.md b/content/en/api/beta/messages/batches/retrieve.md index e90385f83..02fb8b625 100644 --- a/content/en/api/beta/messages/batches/retrieve.md +++ b/content/en/api/beta/messages/batches/retrieve.md @@ -20,7 +20,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch = object { id, archived_at, cancel_initiated_at, 7 more }` diff --git a/content/en/api/beta/messages/count_tokens.md b/content/en/api/beta/messages/count_tokens.md index b678e5997..070caad1d 100644 --- a/content/en/api/beta/messages/count_tokens.md +++ b/content/en/api/beta/messages/count_tokens.md @@ -16,7 +16,7 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -60,8 +60,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Body Parameters - `messages: array of BetaMessageParam` @@ -2641,15 +2639,19 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4652,6 +4654,6 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ "role": "user" } ], - "model": "claude-opus-4-6" + "model": "claude-mythos-preview" }' ``` diff --git a/content/en/api/beta/messages/create.md b/content/en/api/beta/messages/create.md index 412d127ef..6e3e737c1 100644 --- a/content/en/api/beta/messages/create.md +++ b/content/en/api/beta/messages/create.md @@ -16,7 +16,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -60,8 +60,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Body Parameters - `max_tokens: number` @@ -2649,15 +2647,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4726,10 +4728,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. -- `user_profile_id: optional string` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - ### Returns - `BetaMessage = object { id, container, content, 8 more }` @@ -5653,15 +5651,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/beta/models.md b/content/en/api/beta/models.md index ddf8c392a..dffbab4af 100644 --- a/content/en/api/beta/models.md +++ b/content/en/api/beta/models.md @@ -32,7 +32,7 @@ The Models API response can be used to determine which models are available for - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -76,8 +76,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of BetaModelInfo` @@ -304,7 +302,7 @@ The Models API response can be used to determine information about a specific mo - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -348,8 +346,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaModelInfo = object { id, capabilities, created_at, 4 more }` diff --git a/content/en/api/beta/models/list.md b/content/en/api/beta/models/list.md index 261cff20d..6f5d6440e 100644 --- a/content/en/api/beta/models/list.md +++ b/content/en/api/beta/models/list.md @@ -30,7 +30,7 @@ The Models API response can be used to determine which models are available for - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of BetaModelInfo` diff --git a/content/en/api/beta/models/retrieve.md b/content/en/api/beta/models/retrieve.md index b560585a2..89fc834e8 100644 --- a/content/en/api/beta/models/retrieve.md +++ b/content/en/api/beta/models/retrieve.md @@ -20,7 +20,7 @@ The Models API response can be used to determine information about a specific mo - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaModelInfo = object { id, capabilities, created_at, 4 more }` diff --git a/content/en/api/beta/sessions.md b/content/en/api/beta/sessions.md new file mode 100644 index 000000000..729f33c01 --- /dev/null +++ b/content/en/api/beta/sessions.md @@ -0,0 +1,14204 @@ +# Sessions + +## Create + +**post** `/v1/sessions` + +Create Session + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `agent: string or BetaManagedAgentsAgentParams` + + Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `UnionMember0 = string` + + - `BetaManagedAgentsAgentParams = object { id, type, version }` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: string` + + The `agent` ID. + + - `type: "agent"` + + - `"agent"` + + - `version: optional number` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +- `environment_id: string` + + ID of the `environment` defining the container configuration for this session. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata attached to the session. + +- `resources: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams` + + Resources (e.g. repositories, files) to mount into the session's container. + + - `BetaManagedAgentsGitHubRepositoryResourceParams = object { authorization_token, type, url, 2 more }` + + Mount a GitHub repository into the session's container. + + - `authorization_token: string` + + GitHub authorization token used to clone the repository. + + - `type: "github_repository"` + + - `"github_repository"` + + - `url: string` + + Github URL of the repository + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/workspace/`. + + - `BetaManagedAgentsFileResourceParams = object { file_id, type, mount_path }` + + Mount a file uploaded via the Files API into the session. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `title: optional string` + + Human-readable session title. + +- `vault_ids: optional array of string` + + Vault IDs for stored credentials the agent can use during the session. + +### Returns + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "agent": "agent_011CZkYpogX7uDKUyvBTophP", + "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW" + }' +``` + +## List + +**get** `/v1/sessions` + +List Sessions + +### Query Parameters + +- `agent_id: optional string` + + Filter sessions created with this agent ID. + +- `agent_version: optional number` + + Filter by agent version. Only applies when agent_id is also set. + +- `"created_at[gt]": optional string` + + Return sessions created after this time (exclusive). + +- `"created_at[gte]": optional string` + + Return sessions created at or after this time (inclusive). + +- `"created_at[lt]": optional string` + + Return sessions created before this time (exclusive). + +- `"created_at[lte]": optional string` + + Return sessions created at or before this time (inclusive). + +- `include_archived: optional boolean` + + When true, includes archived sessions. Default: false (exclude archived). + +- `limit: optional number` + + Maximum number of results to return. + +- `order: optional "asc" or "desc"` + + Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `"asc"` + + - `"desc"` + +- `page: optional string` + + Opaque pagination cursor from a previous response's next_page. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsSession` + + List of sessions. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + +- `title: optional string` + + Human-readable session title. + +- `vault_ids: optional array of string` + + Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +### Returns + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{}' +``` + +## Delete + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedSession = object { id, type }` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Archive + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `BetaManagedAgentsAgentParams = object { id, type, version }` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: string` + + The `agent` ID. + + - `type: "agent"` + + - `"agent"` + + - `version: optional number` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + +### Beta Managed Agents Cache Creation Usage + +- `BetaManagedAgentsCacheCreationUsage = object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Deleted Session + +- `BetaManagedAgentsDeletedSession = object { id, type }` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Beta Managed Agents File Resource Params + +- `BetaManagedAgentsFileResourceParams = object { file_id, type, mount_path }` + + Mount a file uploaded via the Files API into the session. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `BetaManagedAgentsGitHubRepositoryResourceParams = object { authorization_token, type, url, 2 more }` + + Mount a GitHub repository into the session's container. + + - `authorization_token: string` + + GitHub authorization token used to clone the repository. + + - `type: "github_repository"` + + - `"github_repository"` + + - `url: string` + + Github URL of the repository + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `BetaManagedAgentsSessionAgent = object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + +### Beta Managed Agents Session Stats + +- `BetaManagedAgentsSessionStats = object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `BetaManagedAgentsSessionUsage = object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + +# Events + +## List + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Path Parameters + +- `session_id: string` + +### Query Parameters + +- `limit: optional number` + + Query parameter for limit + +- `order: optional "asc" or "desc"` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"` + + - `"desc"` + +- `page: optional string` + + Opaque pagination cursor from a previous response's next_page. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsSessionEvent` + + Events for the session, ordered by `created_at`. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Send + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `events: array of BetaManagedAgentsEventParams` + + Events to send to the `session`. + + - `BetaManagedAgentsUserMessageEventParams = object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams = object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams = object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams = object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Returns + +- `BetaManagedAgentsSendSessionEvents = object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "events": [ + { + "content": [ + { + "text": "Where is my order #1234?", + "type": "text" + } + ], + "type": "user.message" + } + ] + }' +``` + +## Stream + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Agent Message Event + +- `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Base64 Document Source + +- `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Base64 Image Source + +- `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Billing Error + +- `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + +### Beta Managed Agents Document Block + +- `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + +### Beta Managed Agents Event Params + +- `BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserInterruptEventParams or BetaManagedAgentsUserToolConfirmationEventParams or BetaManagedAgentsUserCustomToolResultEventParams` + + Union type for event parameters that can be sent to a session. + + - `BetaManagedAgentsUserMessageEventParams = object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams = object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams = object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams = object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents File Image Source + +- `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents Image Block + +- `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Retry Status Exhausted + +- `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + +### Beta Managed Agents Send Session Events + +- `BetaManagedAgentsSendSessionEvents = object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + +### Beta Managed Agents Session Error Event + +- `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + +### Beta Managed Agents Session Event + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Union type for all event types in a session. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `BetaManagedAgentsSpanModelUsage = object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Stream Session Events + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Text Block + +- `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Unknown Error + +- `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + +### Beta Managed Agents URL Document Source + +- `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `BetaManagedAgentsUserCustomToolResultEventParams = object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `BetaManagedAgentsUserInterruptEventParams = object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `BetaManagedAgentsUserMessageEventParams = object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `BetaManagedAgentsUserToolConfirmationEventParams = object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `file_id: string` + + ID of a previously uploaded file. + +- `type: "file"` + + - `"file"` + +- `mount_path: optional string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Returns + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", + "type": "file" + }' +``` + +## List + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Path Parameters + +- `session_id: string` + +### Query Parameters + +- `limit: optional number` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `page: optional string` + + Opaque cursor from a previous response's next_page field. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: array of BetaManagedAgentsSessionResource` + + Resources for the session, ordered by `created_at`. + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Path Parameters + +- `session_id: string` + +- `resource_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Path Parameters + +- `session_id: string` + +- `resource_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `authorization_token: string` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +### Returns + +- `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "authorization_token": "ghp_exampletoken" + }' +``` + +## Delete + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Path Parameters + +- `session_id: string` + +- `resource_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeleteSessionResource = object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `BetaManagedAgentsDeleteSessionResource = object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Session Resource + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Resource Retrieve Response + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The requested session resource. + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Resource Update Response + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The updated session resource. + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format diff --git a/content/en/api/beta/sessions/archive.md b/content/en/api/beta/sessions/archive.md new file mode 100644 index 000000000..a5780fa29 --- /dev/null +++ b/content/en/api/beta/sessions/archive.md @@ -0,0 +1,501 @@ +## Archive + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/sessions/create.md b/content/en/api/beta/sessions/create.md new file mode 100644 index 000000000..8b899a9a5 --- /dev/null +++ b/content/en/api/beta/sessions/create.md @@ -0,0 +1,605 @@ +## Create + +**post** `/v1/sessions` + +Create Session + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `agent: string or BetaManagedAgentsAgentParams` + + Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `UnionMember0 = string` + + - `BetaManagedAgentsAgentParams = object { id, type, version }` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: string` + + The `agent` ID. + + - `type: "agent"` + + - `"agent"` + + - `version: optional number` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +- `environment_id: string` + + ID of the `environment` defining the container configuration for this session. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata attached to the session. + +- `resources: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams` + + Resources (e.g. repositories, files) to mount into the session's container. + + - `BetaManagedAgentsGitHubRepositoryResourceParams = object { authorization_token, type, url, 2 more }` + + Mount a GitHub repository into the session's container. + + - `authorization_token: string` + + GitHub authorization token used to clone the repository. + + - `type: "github_repository"` + + - `"github_repository"` + + - `url: string` + + Github URL of the repository + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/workspace/`. + + - `BetaManagedAgentsFileResourceParams = object { file_id, type, mount_path }` + + Mount a file uploaded via the Files API into the session. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `title: optional string` + + Human-readable session title. + +- `vault_ids: optional array of string` + + Vault IDs for stored credentials the agent can use during the session. + +### Returns + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "agent": "agent_011CZkYpogX7uDKUyvBTophP", + "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW" + }' +``` diff --git a/content/en/api/beta/sessions/delete.md b/content/en/api/beta/sessions/delete.md new file mode 100644 index 000000000..3c78010e1 --- /dev/null +++ b/content/en/api/beta/sessions/delete.md @@ -0,0 +1,83 @@ +## Delete + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedSession = object { id, type }` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/sessions/events.md b/content/en/api/beta/sessions/events.md new file mode 100644 index 000000000..e56fe8478 --- /dev/null +++ b/content/en/api/beta/sessions/events.md @@ -0,0 +1,9636 @@ +# Events + +## List + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Path Parameters + +- `session_id: string` + +### Query Parameters + +- `limit: optional number` + + Query parameter for limit + +- `order: optional "asc" or "desc"` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"` + + - `"desc"` + +- `page: optional string` + + Opaque pagination cursor from a previous response's next_page. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsSessionEvent` + + Events for the session, ordered by `created_at`. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Send + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `events: array of BetaManagedAgentsEventParams` + + Events to send to the `session`. + + - `BetaManagedAgentsUserMessageEventParams = object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams = object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams = object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams = object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Returns + +- `BetaManagedAgentsSendSessionEvents = object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "events": [ + { + "content": [ + { + "text": "Where is my order #1234?", + "type": "text" + } + ], + "type": "user.message" + } + ] + }' +``` + +## Stream + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Agent Message Event + +- `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Base64 Document Source + +- `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Base64 Image Source + +- `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Billing Error + +- `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + +### Beta Managed Agents Document Block + +- `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + +### Beta Managed Agents Event Params + +- `BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserInterruptEventParams or BetaManagedAgentsUserToolConfirmationEventParams or BetaManagedAgentsUserCustomToolResultEventParams` + + Union type for event parameters that can be sent to a session. + + - `BetaManagedAgentsUserMessageEventParams = object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams = object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams = object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams = object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents File Image Source + +- `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents Image Block + +- `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Retry Status Exhausted + +- `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + +### Beta Managed Agents Send Session Events + +- `BetaManagedAgentsSendSessionEvents = object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + +### Beta Managed Agents Session Error Event + +- `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + +### Beta Managed Agents Session Event + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Union type for all event types in a session. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `BetaManagedAgentsSpanModelUsage = object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Stream Session Events + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Text Block + +- `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Unknown Error + +- `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + +### Beta Managed Agents URL Document Source + +- `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `BetaManagedAgentsUserCustomToolResultEventParams = object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `BetaManagedAgentsUserInterruptEventParams = object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `BetaManagedAgentsUserMessageEventParams = object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `BetaManagedAgentsUserToolConfirmationEventParams = object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. diff --git a/content/en/api/beta/sessions/events/list.md b/content/en/api/beta/sessions/events/list.md new file mode 100644 index 000000000..962f1b8cb --- /dev/null +++ b/content/en/api/beta/sessions/events/list.md @@ -0,0 +1,1462 @@ +## List + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Path Parameters + +- `session_id: string` + +### Query Parameters + +- `limit: optional number` + + Query parameter for limit + +- `order: optional "asc" or "desc"` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"` + + - `"desc"` + +- `page: optional string` + + Opaque pagination cursor from a previous response's next_page. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsSessionEvent` + + Events for the session, ordered by `created_at`. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/sessions/events/send.md b/content/en/api/beta/sessions/events/send.md new file mode 100644 index 000000000..4dad96e46 --- /dev/null +++ b/content/en/api/beta/sessions/events/send.md @@ -0,0 +1,828 @@ +## Send + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `events: array of BetaManagedAgentsEventParams` + + Events to send to the `session`. + + - `BetaManagedAgentsUserMessageEventParams = object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams = object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams = object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams = object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Returns + +- `BetaManagedAgentsSendSessionEvents = object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "events": [ + { + "content": [ + { + "text": "Where is my order #1234?", + "type": "text" + } + ], + "type": "user.message" + } + ] + }' +``` diff --git a/content/en/api/beta/sessions/events/stream.md b/content/en/api/beta/sessions/events/stream.md new file mode 100644 index 000000000..68d554a13 --- /dev/null +++ b/content/en/api/beta/sessions/events/stream.md @@ -0,0 +1,1440 @@ +## Stream + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent = object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent = object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent = object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent = object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent = object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent = object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent = object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent = object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent = object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent = object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent = object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock = object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock = object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource = object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource = object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource = object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock = object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource = object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource = object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource = object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource = object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent = object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent = object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError = object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError = object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError = object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError = object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError = object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError = object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError = object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying = object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted = object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal = object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent = object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent = object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent = object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn = object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction = object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted = object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent = object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent = object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent = object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent = object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/sessions/list.md b/content/en/api/beta/sessions/list.md new file mode 100644 index 000000000..4e79f2393 --- /dev/null +++ b/content/en/api/beta/sessions/list.md @@ -0,0 +1,546 @@ +## List + +**get** `/v1/sessions` + +List Sessions + +### Query Parameters + +- `agent_id: optional string` + + Filter sessions created with this agent ID. + +- `agent_version: optional number` + + Filter by agent version. Only applies when agent_id is also set. + +- `"created_at[gt]": optional string` + + Return sessions created after this time (exclusive). + +- `"created_at[gte]": optional string` + + Return sessions created at or after this time (inclusive). + +- `"created_at[lt]": optional string` + + Return sessions created before this time (exclusive). + +- `"created_at[lte]": optional string` + + Return sessions created at or before this time (inclusive). + +- `include_archived: optional boolean` + + When true, includes archived sessions. Default: false (exclude archived). + +- `limit: optional number` + + Maximum number of results to return. + +- `order: optional "asc" or "desc"` + + Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `"asc"` + + - `"desc"` + +- `page: optional string` + + Opaque pagination cursor from a previous response's next_page. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsSession` + + List of sessions. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/sessions/resources.md b/content/en/api/beta/sessions/resources.md new file mode 100644 index 000000000..4911c2b6b --- /dev/null +++ b/content/en/api/beta/sessions/resources.md @@ -0,0 +1,918 @@ +# Resources + +## Add + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `file_id: string` + + ID of a previously uploaded file. + +- `type: "file"` + + - `"file"` + +- `mount_path: optional string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Returns + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", + "type": "file" + }' +``` + +## List + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Path Parameters + +- `session_id: string` + +### Query Parameters + +- `limit: optional number` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `page: optional string` + + Opaque cursor from a previous response's next_page field. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: array of BetaManagedAgentsSessionResource` + + Resources for the session, ordered by `created_at`. + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Path Parameters + +- `session_id: string` + +- `resource_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Path Parameters + +- `session_id: string` + +- `resource_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `authorization_token: string` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +### Returns + +- `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "authorization_token": "ghp_exampletoken" + }' +``` + +## Delete + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Path Parameters + +- `session_id: string` + +- `resource_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeleteSessionResource = object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `BetaManagedAgentsDeleteSessionResource = object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Session Resource + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Resource Retrieve Response + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The requested session resource. + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Resource Update Response + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The updated session resource. + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format diff --git a/content/en/api/beta/sessions/resources/add.md b/content/en/api/beta/sessions/resources/add.md new file mode 100644 index 000000000..adfab20dd --- /dev/null +++ b/content/en/api/beta/sessions/resources/add.md @@ -0,0 +1,111 @@ +## Add + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `file_id: string` + + ID of a previously uploaded file. + +- `type: "file"` + + - `"file"` + +- `mount_path: optional string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Returns + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", + "type": "file" + }' +``` diff --git a/content/en/api/beta/sessions/resources/delete.md b/content/en/api/beta/sessions/resources/delete.md new file mode 100644 index 000000000..d7c0c3758 --- /dev/null +++ b/content/en/api/beta/sessions/resources/delete.md @@ -0,0 +1,85 @@ +## Delete + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Path Parameters + +- `session_id: string` + +- `resource_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeleteSessionResource = object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/sessions/resources/list.md b/content/en/api/beta/sessions/resources/list.md new file mode 100644 index 000000000..0a7e353d5 --- /dev/null +++ b/content/en/api/beta/sessions/resources/list.md @@ -0,0 +1,152 @@ +## List + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Path Parameters + +- `session_id: string` + +### Query Parameters + +- `limit: optional number` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `page: optional string` + + Opaque cursor from a previous response's next_page field. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: array of BetaManagedAgentsSessionResource` + + Resources for the session, ordered by `created_at`. + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +- `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/sessions/resources/retrieve.md b/content/en/api/beta/sessions/resources/retrieve.md new file mode 100644 index 000000000..21a3a3335 --- /dev/null +++ b/content/en/api/beta/sessions/resources/retrieve.md @@ -0,0 +1,136 @@ +## Retrieve + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Path Parameters + +- `session_id: string` + +- `resource_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/sessions/resources/update.md b/content/en/api/beta/sessions/resources/update.md new file mode 100644 index 000000000..c88941f2e --- /dev/null +++ b/content/en/api/beta/sessions/resources/update.md @@ -0,0 +1,146 @@ +## Update + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Path Parameters + +- `session_id: string` + +- `resource_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `authorization_token: string` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +### Returns + +- `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +- `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "authorization_token": "ghp_exampletoken" + }' +``` diff --git a/content/en/api/beta/sessions/retrieve.md b/content/en/api/beta/sessions/retrieve.md new file mode 100644 index 000000000..b0e453597 --- /dev/null +++ b/content/en/api/beta/sessions/retrieve.md @@ -0,0 +1,500 @@ +## Retrieve + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/sessions/update.md b/content/en/api/beta/sessions/update.md new file mode 100644 index 000000000..f84bec474 --- /dev/null +++ b/content/en/api/beta/sessions/update.md @@ -0,0 +1,516 @@ +## Update + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Path Parameters + +- `session_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + +- `title: optional string` + + Human-readable session title. + +- `vault_ids: optional array of string` + + Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +### Returns + +- `BetaManagedAgentsSession = object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `UnionMember1 = string` + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `BetaManagedAgentsAnthropicSkill = object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill = object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `BetaManagedAgentsAgentToolset20260401 = object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset = object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy = object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy = object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool = object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `BetaManagedAgentsGitHubRepositoryResource = object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `BetaManagedAgentsBranchCheckout = object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout = object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource = object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```http +curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{}' +``` diff --git a/content/en/api/beta/skills.md b/content/en/api/beta/skills.md index 1f0df159b..ed7d5b024 100644 --- a/content/en/api/beta/skills.md +++ b/content/en/api/beta/skills.md @@ -14,7 +14,7 @@ Create Skill - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -58,8 +58,6 @@ Create Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -150,7 +148,7 @@ List Skills - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -194,8 +192,6 @@ List Skills - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of object { id, created_at, display_title, 4 more }` @@ -286,7 +282,7 @@ Get Skill - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -330,8 +326,6 @@ Get Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -406,7 +400,7 @@ Delete Skill - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -450,8 +444,6 @@ Delete Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -653,7 +645,7 @@ Create Skill Version - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -697,8 +689,6 @@ Create Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -789,7 +779,7 @@ List Skill Versions - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -833,8 +823,6 @@ List Skill Versions - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of object { id, created_at, description, 5 more }` @@ -930,7 +918,7 @@ Get Skill Version - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -974,8 +962,6 @@ Get Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -1059,7 +1045,7 @@ Delete Skill Version - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -1103,8 +1089,6 @@ Delete Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` diff --git a/content/en/api/beta/skills/create.md b/content/en/api/beta/skills/create.md index e8f013249..f88f83b3a 100644 --- a/content/en/api/beta/skills/create.md +++ b/content/en/api/beta/skills/create.md @@ -12,7 +12,7 @@ Create Skill - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -56,8 +56,6 @@ Create Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` diff --git a/content/en/api/beta/skills/delete.md b/content/en/api/beta/skills/delete.md index 084cbefc1..8b851bfd9 100644 --- a/content/en/api/beta/skills/delete.md +++ b/content/en/api/beta/skills/delete.md @@ -20,7 +20,7 @@ Delete Skill - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Delete Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` diff --git a/content/en/api/beta/skills/list.md b/content/en/api/beta/skills/list.md index 29bec9902..cd5d18ba1 100644 --- a/content/en/api/beta/skills/list.md +++ b/content/en/api/beta/skills/list.md @@ -35,7 +35,7 @@ List Skills - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -79,8 +79,6 @@ List Skills - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of object { id, created_at, display_title, 4 more }` diff --git a/content/en/api/beta/skills/retrieve.md b/content/en/api/beta/skills/retrieve.md index 814464b43..cb9e6b894 100644 --- a/content/en/api/beta/skills/retrieve.md +++ b/content/en/api/beta/skills/retrieve.md @@ -20,7 +20,7 @@ Get Skill - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Get Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` diff --git a/content/en/api/beta/skills/versions.md b/content/en/api/beta/skills/versions.md index 7ae4e5869..47a0a8d34 100644 --- a/content/en/api/beta/skills/versions.md +++ b/content/en/api/beta/skills/versions.md @@ -22,7 +22,7 @@ Create Skill Version - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Create Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -158,7 +156,7 @@ List Skill Versions - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -202,8 +200,6 @@ List Skill Versions - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of object { id, created_at, description, 5 more }` @@ -299,7 +295,7 @@ Get Skill Version - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -343,8 +339,6 @@ Get Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` @@ -428,7 +422,7 @@ Delete Skill Version - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -472,8 +466,6 @@ Delete Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` diff --git a/content/en/api/beta/skills/versions/create.md b/content/en/api/beta/skills/versions/create.md index 1fb7211be..78ad908da 100644 --- a/content/en/api/beta/skills/versions/create.md +++ b/content/en/api/beta/skills/versions/create.md @@ -20,7 +20,7 @@ Create Skill Version - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Create Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` diff --git a/content/en/api/beta/skills/versions/delete.md b/content/en/api/beta/skills/versions/delete.md index a60aee72e..dc079d54c 100644 --- a/content/en/api/beta/skills/versions/delete.md +++ b/content/en/api/beta/skills/versions/delete.md @@ -26,7 +26,7 @@ Delete Skill Version - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -70,8 +70,6 @@ Delete Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` diff --git a/content/en/api/beta/skills/versions/list.md b/content/en/api/beta/skills/versions/list.md index bb30a46ab..0d8b01677 100644 --- a/content/en/api/beta/skills/versions/list.md +++ b/content/en/api/beta/skills/versions/list.md @@ -32,7 +32,7 @@ List Skill Versions - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -76,8 +76,6 @@ List Skill Versions - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of object { id, created_at, description, 5 more }` diff --git a/content/en/api/beta/skills/versions/retrieve.md b/content/en/api/beta/skills/versions/retrieve.md index 8196ae049..09be09718 100644 --- a/content/en/api/beta/skills/versions/retrieve.md +++ b/content/en/api/beta/skills/versions/retrieve.md @@ -26,7 +26,7 @@ Get Skill Version - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -70,8 +70,6 @@ Get Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `id: string` diff --git a/content/en/api/beta/vaults.md b/content/en/api/beta/vaults.md new file mode 100644 index 000000000..96477b6f3 --- /dev/null +++ b/content/en/api/beta/vaults.md @@ -0,0 +1,2597 @@ +# Vaults + +## Create + +**post** `/v1/vaults` + +Create Vault + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `display_name: string` + + Human-readable name for the vault. 1-255 characters. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata to attach to the vault. + +### Returns + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/vaults \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "display_name": "Example vault" + }' +``` + +## List + +**get** `/v1/vaults` + +List Vaults + +### Query Parameters + +- `include_archived: optional boolean` + + Whether to include archived vaults in the results. + +- `limit: optional number` + + Maximum number of vaults to return per page. Defaults to 20, maximum 100. + +- `page: optional string` + + Opaque pagination token from a previous `list_vaults` response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsVault` + + List of vaults. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +- `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `display_name: optional string` + + Updated human-readable name for the vault. 1-255 characters. + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +### Returns + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{}' +``` + +## Delete + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedVault = object { id, type }` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Archive + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `BetaManagedAgentsDeletedVault = object { id, type }` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Beta Managed Agents Vault + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `auth: BetaManagedAgentsMCPOAuthCreateParams or BetaManagedAgentsStaticBearerCreateParams` + + Authentication details for creating a credential. + + - `BetaManagedAgentsMCPOAuthCreateParams = object { access_token, mcp_server_url, type, 2 more }` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerCreateParams = object { token, mcp_server_url, type }` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +- `display_name: optional string` + + Human-readable name for the credential. Up to 255 characters. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata to attach to the credential. + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "auth": { + "token": "bearer_exampletoken", + "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", + "type": "static_bearer" + } + }' +``` + +## List + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Path Parameters + +- `vault_id: string` + +### Query Parameters + +- `include_archived: optional boolean` + + Whether to include archived credentials in the results. + +- `limit: optional number` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `page: optional string` + + Opaque pagination token from a previous `list_credentials` response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsCredential` + + List of credentials. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +- `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `auth: optional BetaManagedAgentsMCPOAuthUpdateParams or BetaManagedAgentsStaticBearerUpdateParams` + + Updated authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthUpdateParams = object { type, access_token, expires_at, refresh }` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token: optional string` + + Updated OAuth access token. + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsStaticBearerUpdateParams = object { type, token }` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token: optional string` + + Updated static bearer token value. + +- `display_name: optional string` + + Updated human-readable name for the credential. 1-255 characters. + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{}' +``` + +## Delete + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedCredential = object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Archive + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `BetaManagedAgentsDeletedCredential = object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `BetaManagedAgentsMCPOAuthCreateParams = object { access_token, mcp_server_url, type, 2 more }` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `BetaManagedAgentsMCPOAuthRefreshParams = object { client_id, refresh_token, token_endpoint, 3 more }` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `BetaManagedAgentsMCPOAuthRefreshResponse = object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `BetaManagedAgentsMCPOAuthRefreshUpdateParams = object { refresh_token, scope, token_endpoint_auth }` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `BetaManagedAgentsMCPOAuthUpdateParams = object { type, access_token, expires_at, refresh }` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token: optional string` + + Updated OAuth access token. + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `BetaManagedAgentsStaticBearerCreateParams = object { token, mcp_server_url, type }` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `BetaManagedAgentsStaticBearerUpdateParams = object { type, token }` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token: optional string` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. diff --git a/content/en/api/beta/vaults/archive.md b/content/en/api/beta/vaults/archive.md new file mode 100644 index 000000000..22a562225 --- /dev/null +++ b/content/en/api/beta/vaults/archive.md @@ -0,0 +1,105 @@ +## Archive + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/vaults/create.md b/content/en/api/beta/vaults/create.md new file mode 100644 index 000000000..a3334d625 --- /dev/null +++ b/content/en/api/beta/vaults/create.md @@ -0,0 +1,114 @@ +## Create + +**post** `/v1/vaults` + +Create Vault + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `display_name: string` + + Human-readable name for the vault. 1-255 characters. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata to attach to the vault. + +### Returns + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/vaults \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "display_name": "Example vault" + }' +``` diff --git a/content/en/api/beta/vaults/credentials.md b/content/en/api/beta/vaults/credentials.md new file mode 100644 index 000000000..48789a7ef --- /dev/null +++ b/content/en/api/beta/vaults/credentials.md @@ -0,0 +1,1897 @@ +# Credentials + +## Create + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `auth: BetaManagedAgentsMCPOAuthCreateParams or BetaManagedAgentsStaticBearerCreateParams` + + Authentication details for creating a credential. + + - `BetaManagedAgentsMCPOAuthCreateParams = object { access_token, mcp_server_url, type, 2 more }` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerCreateParams = object { token, mcp_server_url, type }` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +- `display_name: optional string` + + Human-readable name for the credential. Up to 255 characters. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata to attach to the credential. + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "auth": { + "token": "bearer_exampletoken", + "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", + "type": "static_bearer" + } + }' +``` + +## List + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Path Parameters + +- `vault_id: string` + +### Query Parameters + +- `include_archived: optional boolean` + + Whether to include archived credentials in the results. + +- `limit: optional number` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `page: optional string` + + Opaque pagination token from a previous `list_credentials` response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsCredential` + + List of credentials. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +- `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Retrieve + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Update + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `auth: optional BetaManagedAgentsMCPOAuthUpdateParams or BetaManagedAgentsStaticBearerUpdateParams` + + Updated authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthUpdateParams = object { type, access_token, expires_at, refresh }` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token: optional string` + + Updated OAuth access token. + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsStaticBearerUpdateParams = object { type, token }` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token: optional string` + + Updated static bearer token value. + +- `display_name: optional string` + + Updated human-readable name for the credential. 1-255 characters. + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{}' +``` + +## Delete + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedCredential = object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Archive + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `BetaManagedAgentsDeletedCredential = object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `BetaManagedAgentsMCPOAuthCreateParams = object { access_token, mcp_server_url, type, 2 more }` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `BetaManagedAgentsMCPOAuthRefreshParams = object { client_id, refresh_token, token_endpoint, 3 more }` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `BetaManagedAgentsMCPOAuthRefreshResponse = object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `BetaManagedAgentsMCPOAuthRefreshUpdateParams = object { refresh_token, scope, token_endpoint_auth }` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `BetaManagedAgentsMCPOAuthUpdateParams = object { type, access_token, expires_at, refresh }` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token: optional string` + + Updated OAuth access token. + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `BetaManagedAgentsStaticBearerCreateParams = object { token, mcp_server_url, type }` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `BetaManagedAgentsStaticBearerUpdateParams = object { type, token }` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token: optional string` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. diff --git a/content/en/api/beta/vaults/credentials/archive.md b/content/en/api/beta/vaults/credentials/archive.md new file mode 100644 index 000000000..976f84290 --- /dev/null +++ b/content/en/api/beta/vaults/credentials/archive.md @@ -0,0 +1,191 @@ +## Archive + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID/archive \ + -X POST \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/vaults/credentials/create.md b/content/en/api/beta/vaults/credentials/create.md new file mode 100644 index 000000000..8d0880a4a --- /dev/null +++ b/content/en/api/beta/vaults/credentials/create.md @@ -0,0 +1,306 @@ +## Create + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `auth: BetaManagedAgentsMCPOAuthCreateParams or BetaManagedAgentsStaticBearerCreateParams` + + Authentication details for creating a credential. + + - `BetaManagedAgentsMCPOAuthCreateParams = object { access_token, mcp_server_url, type, 2 more }` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam = object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam = object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerCreateParams = object { token, mcp_server_url, type }` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +- `display_name: optional string` + + Human-readable name for the credential. Up to 255 characters. + +- `metadata: optional map[string]` + + Arbitrary key-value metadata to attach to the credential. + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "auth": { + "token": "bearer_exampletoken", + "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", + "type": "static_bearer" + } + }' +``` diff --git a/content/en/api/beta/vaults/credentials/delete.md b/content/en/api/beta/vaults/credentials/delete.md new file mode 100644 index 000000000..dd3cfe65e --- /dev/null +++ b/content/en/api/beta/vaults/credentials/delete.md @@ -0,0 +1,87 @@ +## Delete + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedCredential = object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/vaults/credentials/list.md b/content/en/api/beta/vaults/credentials/list.md new file mode 100644 index 000000000..9ded3b361 --- /dev/null +++ b/content/en/api/beta/vaults/credentials/list.md @@ -0,0 +1,206 @@ +## List + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Path Parameters + +- `vault_id: string` + +### Query Parameters + +- `include_archived: optional boolean` + + Whether to include archived credentials in the results. + +- `limit: optional number` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `page: optional string` + + Opaque pagination token from a previous `list_credentials` response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsCredential` + + List of credentials. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +- `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/vaults/credentials/retrieve.md b/content/en/api/beta/vaults/credentials/retrieve.md new file mode 100644 index 000000000..f7481b119 --- /dev/null +++ b/content/en/api/beta/vaults/credentials/retrieve.md @@ -0,0 +1,190 @@ +## Retrieve + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/vaults/credentials/update.md b/content/en/api/beta/vaults/credentials/update.md new file mode 100644 index 000000000..5dff6f795 --- /dev/null +++ b/content/en/api/beta/vaults/credentials/update.md @@ -0,0 +1,274 @@ +## Update + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Path Parameters + +- `vault_id: string` + +- `credential_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `auth: optional BetaManagedAgentsMCPOAuthUpdateParams or BetaManagedAgentsStaticBearerUpdateParams` + + Updated authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthUpdateParams = object { type, access_token, expires_at, refresh }` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token: optional string` + + Updated OAuth access token. + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam = object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam = object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `BetaManagedAgentsStaticBearerUpdateParams = object { type, token }` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token: optional string` + + Updated static bearer token value. + +- `display_name: optional string` + + Updated human-readable name for the credential. 1-255 characters. + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +### Returns + +- `BetaManagedAgentsCredential = object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse = object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse = object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse = object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse = object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse = object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{}' +``` diff --git a/content/en/api/beta/vaults/delete.md b/content/en/api/beta/vaults/delete.md new file mode 100644 index 000000000..0ad52d27c --- /dev/null +++ b/content/en/api/beta/vaults/delete.md @@ -0,0 +1,85 @@ +## Delete + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedVault = object { id, type }` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID \ + -X DELETE \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/vaults/list.md b/content/en/api/beta/vaults/list.md new file mode 100644 index 000000000..8467026b6 --- /dev/null +++ b/content/en/api/beta/vaults/list.md @@ -0,0 +1,118 @@ +## List + +**get** `/v1/vaults` + +List Vaults + +### Query Parameters + +- `include_archived: optional boolean` + + Whether to include archived vaults in the results. + +- `limit: optional number` + + Maximum number of vaults to return per page. Defaults to 20, maximum 100. + +- `page: optional string` + + Opaque pagination token from a previous `list_vaults` response. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `data: optional array of BetaManagedAgentsVault` + + List of vaults. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +- `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```http +curl https://api.anthropic.com/v1/vaults \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/vaults/retrieve.md b/content/en/api/beta/vaults/retrieve.md new file mode 100644 index 000000000..1ea0c7298 --- /dev/null +++ b/content/en/api/beta/vaults/retrieve.md @@ -0,0 +1,104 @@ +## Retrieve + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/content/en/api/beta/vaults/update.md b/content/en/api/beta/vaults/update.md new file mode 100644 index 000000000..1c81005c8 --- /dev/null +++ b/content/en/api/beta/vaults/update.md @@ -0,0 +1,116 @@ +## Update + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Path Parameters + +- `vault_id: string` + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Body Parameters + +- `display_name: optional string` + + Updated human-readable name for the vault. 1-255 characters. + +- `metadata: optional map[string]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +### Returns + +- `BetaManagedAgentsVault = object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```http +curl https://api.anthropic.com/v1/vaults/$VAULT_ID \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H 'anthropic-beta: managed-agents-2026-04-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{}' +``` diff --git a/content/en/api/cli/beta.md b/content/en/api/cli/beta.md index 91ff456cc..49789ce5a 100644 --- a/content/en/api/cli/beta.md +++ b/content/en/api/cli/beta.md @@ -1 +1,47814 @@ -Not Found - Claude API Docs
    \ No newline at end of file +# Beta + +## Domain Types + +### Beta API Error + +- `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + +### Beta Authentication Error + +- `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + +### Beta Billing Error + +- `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + +### Beta Error + +- `beta_error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + +### Beta Error Response + +- `beta_error_response: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + +### Beta Gateway Timeout Error + +- `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + +### Beta Invalid Request Error + +- `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + +### Beta Not Found Error + +- `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + +### Beta Overloaded Error + +- `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + +### Beta Permission Error + +- `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + +### Beta Rate Limit Error + +- `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + +# Models + +## List + +`$ ant beta:models list` + +**get** `/v1/models` + +List available models. + +The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first. + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListResponse_ModelInfo_: object { data, first_id, has_more, last_id }` + + - `data: array of BetaModelInfo` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant beta:models list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant beta:models retrieve` + +**get** `/v1/models/{model_id}` + +Get a specific model. + +The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID. + +### Parameters + +- `--model-id: string` + + Model identifier or alias. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_model_info: object { id, capabilities, created_at, 4 more }` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + +### Example + +```cli +ant beta:models retrieve \ + --api-key my-anthropic-api-key \ + --model-id model_id +``` + +## Domain Types + +### Beta Capability Support + +- `beta_capability_support: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Beta Context Management Capability + +- `beta_context_management_capability: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management capability details. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Beta Effort Capability + +- `beta_effort_capability: object { high, low, max, 2 more }` + + Effort (reasoning_effort) capability details. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Beta Model Capabilities + +- `beta_model_capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Beta Model Info + +- `beta_model_info: object { id, capabilities, created_at, 4 more }` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + +### Beta Thinking Capability + +- `beta_thinking_capability: object { supported, types }` + + Thinking capability details. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Beta Thinking Types + +- `beta_thinking_types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + +# Messages + +## Create + +`$ ant beta:messages create` + +**post** `/v1/messages` + +Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. + +The Messages API can be used for either single queries or stateless multi-turn conversations. + +Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup) + +### Parameters + +- `--max-tokens: number` + + Body param: The maximum number of tokens to generate before stopping. + + Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. + + Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. + +- `--message: array of BetaMessageParam` + + Body param: Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + +- `--model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + Body param: The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--cache-control: optional object { type, ttl }` + + Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--container: optional BetaContainerParams or string` + + Body param: Container identifier for reuse across requests. + +- `--context-management: optional object { edits }` + + Body param: Context management configuration. + + This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. + +- `--inference-geo: optional string` + + Body param: Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. + +- `--mcp-server: optional array of BetaRequestMCPServerURLDefinition` + + Body param: MCP servers to be utilized in this request + +- `--metadata: optional object { user_id }` + + Body param: An object describing metadata about the request. + +- `--output-config: optional object { effort, format }` + + Body param: Configuration options for the model's output, such as the output format. + +- `--output-format: optional object { schema, type }` + + Body param: Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + A schema to specify Claude's output format in responses. This parameter will be removed in a future release. + +- `--service-tier: optional "auto" or "standard_only"` + + Body param: Determines whether to use priority capacity (if available) or standard capacity for this request. + + Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. + +- `--speed: optional "standard" or "fast"` + + Body param: The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. + +- `--stop-sequence: optional array of string` + + Body param: Custom text sequences that will cause the model to stop generating. + + Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. + + If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. + +- `--system: optional string or array of BetaTextBlockParam` + + Body param: System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + +- `--temperature: optional number` + + Body param: Amount of randomness injected into the response. + + Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. + + Note that even with `temperature` of `0.0`, the results will not be fully deterministic. + +- `--thinking: optional BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigAdaptive` + + Body param: Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + +- `--tool-choice: optional BetaToolChoiceAuto or BetaToolChoiceAny or BetaToolChoiceTool or BetaToolChoiceNone` + + Body param: How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + +- `--tool: optional array of BetaToolUnion` + + Body param: Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + +- `--top-k: optional number` + + Body param: Only sample from the top K options for each subsequent token. + + Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--top-p: optional number` + + Body param: Use nucleus sampling. + + In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + +### Example + +```cli +ant beta:messages create \ + --api-key my-anthropic-api-key \ + --max-tokens 1024 \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-opus-4-6 +``` + +## Count Tokens + +`$ ant beta:messages count-tokens` + +**post** `/v1/messages/count_tokens` + +Count the number of tokens in a Message. + +The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it. + +Learn more about token counting in our [user guide](https://docs.claude.com/en/docs/build-with-claude/token-counting) + +### Parameters + +- `--message: array of BetaMessageParam` + + Body param: Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + +- `--model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + Body param: The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--cache-control: optional object { type, ttl }` + + Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--context-management: optional object { edits }` + + Body param: Context management configuration. + + This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. + +- `--mcp-server: optional array of BetaRequestMCPServerURLDefinition` + + Body param: MCP servers to be utilized in this request + +- `--output-config: optional object { effort, format }` + + Body param: Configuration options for the model's output, such as the output format. + +- `--output-format: optional object { schema, type }` + + Body param: Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + A schema to specify Claude's output format in responses. This parameter will be removed in a future release. + +- `--speed: optional "standard" or "fast"` + + Body param: The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. + +- `--system: optional string or array of BetaTextBlockParam` + + Body param: System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + +- `--thinking: optional BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigAdaptive` + + Body param: Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + +- `--tool-choice: optional BetaToolChoiceAuto or BetaToolChoiceAny or BetaToolChoiceTool or BetaToolChoiceNone` + + Body param: How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + +- `--tool: optional array of BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 19 more` + + Body param: Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_tokens_count: object { context_management, input_tokens }` + + - `context_management: object { original_input_tokens }` + + Information about context management applied to the message. + + - `original_input_tokens: number` + + The original token count before context management was applied + + - `input_tokens: number` + + The total number of tokens across the provided list of messages, system prompt, and tools. + +### Example + +```cli +ant beta:messages count-tokens \ + --api-key my-anthropic-api-key \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-mythos-preview +``` + +## Domain Types + +### Beta All Thinking Turns + +- `beta_all_thinking_turns: object { type }` + + - `type: "all"` + +### Beta Base64 Image Source + +- `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + +### Beta Base64 PDF Source + +- `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + +### Beta Bash Code Execution Output Block + +- `beta_bash_code_execution_output_block: object { file_id, type }` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + +### Beta Bash Code Execution Output Block Param + +- `beta_bash_code_execution_output_block_param: object { file_id, type }` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + +### Beta Bash Code Execution Result Block + +- `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + +### Beta Bash Code Execution Result Block Param + +- `beta_bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + +### Beta Bash Code Execution Tool Result Block + +- `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + +### Beta Bash Code Execution Tool Result Block Param + +- `beta_bash_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam` + + - `beta_bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Bash Code Execution Tool Result Error + +- `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + +### Beta Bash Code Execution Tool Result Error Param + +- `beta_bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + +### Beta Cache Control Ephemeral + +- `beta_cache_control_ephemeral: object { type, ttl }` + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Cache Creation + +- `beta_cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + +### Beta Citation Char Location + +- `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + +### Beta Citation Char Location Param + +- `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + +### Beta Citation Config + +- `beta_citation_config: object { enabled }` + + - `enabled: boolean` + +### Beta Citation Content Block Location + +- `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + +### Beta Citation Content Block Location Param + +- `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + +### Beta Citation Page Location + +- `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + +### Beta Citation Page Location Param + +- `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + +### Beta Citation Search Result Location + +- `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Beta Citation Search Result Location Param + +- `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Beta Citation Web Search Result Location Param + +- `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + +### Beta Citations Config Param + +- `beta_citations_config_param: object { enabled }` + + - `enabled: optional boolean` + +### Beta Citations Delta + +- `beta_citations_delta: object { citation, type }` + + - `citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more` + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + +### Beta Citations Web Search Result Location + +- `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + +### Beta Clear Thinking 20251015 Edit + +- `beta_clear_thinking_20251015_edit: object { type, keep }` + + - `type: "clear_thinking_20251015"` + + - `keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"` + + Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. + + - `beta_thinking_turns: object { type, value }` + + - `type: "thinking_turns"` + + - `value: number` + + - `beta_all_thinking_turns: object { type }` + + - `type: "all"` + + - `union_member_2: "all"` + +### Beta Clear Thinking 20251015 Edit Response + +- `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + +### Beta Clear Tool Uses 20250919 Edit + +- `beta_clear_tool_uses_20250919_edit: object { type, clear_at_least, clear_tool_inputs, 3 more }` + + - `type: "clear_tool_uses_20250919"` + + - `clear_at_least: optional object { type, value }` + + Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed. + + - `type: "input_tokens"` + + - `value: number` + + - `clear_tool_inputs: optional boolean or array of string` + + Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) + + - `union_member_0: boolean` + + - `union_member_1: array of string` + + - `exclude_tools: optional array of string` + + Tool names whose uses are preserved from clearing + + - `keep: optional object { type, value }` + + Number of tool uses to retain in the conversation + + - `type: "tool_uses"` + + - `value: number` + + - `trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger` + + Condition that triggers the context management strategy + + - `beta_input_tokens_trigger: object { type, value }` + + - `type: "input_tokens"` + + - `value: number` + + - `beta_tool_uses_trigger: object { type, value }` + + - `type: "tool_uses"` + + - `value: number` + +### Beta Clear Tool Uses 20250919 Edit Response + +- `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + +### Beta Code Execution Output Block + +- `beta_code_execution_output_block: object { file_id, type }` + + - `file_id: string` + + - `type: "code_execution_output"` + +### Beta Code Execution Output Block Param + +- `beta_code_execution_output_block_param: object { file_id, type }` + + - `file_id: string` + + - `type: "code_execution_output"` + +### Beta Code Execution Result Block + +- `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + +### Beta Code Execution Result Block Param + +- `beta_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + +### Beta Code Execution Tool 20250522 + +- `beta_code_execution_tool_20250522: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250522"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Code Execution Tool 20250825 + +- `beta_code_execution_tool_20250825: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250825"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Code Execution Tool 20260120 + +- `beta_code_execution_tool_20260120: object { name, type, allowed_callers, 3 more }` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20260120"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Code Execution Tool Result Block + +- `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + +### Beta Code Execution Tool Result Block Content + +- `beta_code_execution_tool_result_block_content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Beta Code Execution Tool Result Block Param + +- `beta_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaCodeExecutionToolResultErrorParam or BetaCodeExecutionResultBlockParam or BetaEncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Code Execution Tool Result Block Param Content + +- `beta_code_execution_tool_result_block_param_content: BetaCodeExecutionToolResultErrorParam or BetaCodeExecutionResultBlockParam or BetaEncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Beta Code Execution Tool Result Error + +- `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + +### Beta Code Execution Tool Result Error Code + +- `beta_code_execution_tool_result_error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + +### Beta Code Execution Tool Result Error Param + +- `beta_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + +### Beta Compact 20260112 Edit + +- `beta_compact_20260112_edit: object { type, instructions, pause_after_compaction, trigger }` + + Automatically compact older context when reaching the configured trigger threshold. + + - `type: "compact_20260112"` + + - `instructions: optional string` + + Additional instructions for summarization. + + - `pause_after_compaction: optional boolean` + + Whether to pause after compaction and return the compaction block to the user. + + - `trigger: optional object { type, value }` + + When to trigger compaction. Defaults to 150000 input tokens. + + - `type: "input_tokens"` + + - `value: number` + +### Beta Compaction Block + +- `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + +### Beta Compaction Block Param + +- `beta_compaction_block_param: object { content, type, cache_control }` + + A compaction block containing summary of previous context. + + Users should round-trip these blocks from responses to subsequent requests + to maintain context across compaction boundaries. + + When content is None, the block represents a failed compaction. The server + treats these as no-ops. Empty string content is not allowed. + + - `content: string` + + Summary of previously compacted content, or null if compaction failed + + - `type: "compaction"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Compaction Content Block Delta + +- `beta_compaction_content_block_delta: object { content, type }` + + - `content: string` + + - `type: "compaction_delta"` + +### Beta Compaction Iteration Usage + +- `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + +### Beta Container + +- `beta_container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + +### Beta Container Params + +- `beta_container_params: object { id, skills }` + + Container parameters with skills to be loaded. + + - `id: optional string` + + Container id + + - `skills: optional array of BetaSkillParams` + + List of skills to load in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: optional string` + + Skill version or 'latest' for most recent version + +### Beta Container Upload Block + +- `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + +### Beta Container Upload Block Param + +- `beta_container_upload_block_param: object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Content Block + +- `beta_content_block: BetaTextBlock or BetaThinkingBlock or BetaRedactedThinkingBlock or 12 more` + + Response model for a file uploaded to the container. + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + +### Beta Content Block Param + +- `beta_content_block_param: BetaTextBlockParam or BetaImageBlockParam or BetaRequestDocumentBlock or 16 more` + + Regular text content. + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_request_document_block: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `beta_search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `beta_thinking_block_param: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block_param: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `beta_request_document_block: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `beta_tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + + - `beta_server_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: array of BetaWebSearchResultBlockParam or BetaWebSearchToolRequestError` + + - `Result Block: array of BetaWebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `beta_web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam` + + - `beta_web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaCodeExecutionToolResultErrorParam or BetaCodeExecutionResultBlockParam or BetaEncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_bash_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam` + + - `beta_bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_text_editor_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam` + + - `beta_text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `beta_text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `beta_text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_tool_search_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam` + + - `beta_tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_mcp_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_request_mcp_tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional string or array of BetaTextBlockParam` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_param_content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `is_error: optional boolean` + + - `beta_container_upload_block_param: object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_compaction_block_param: object { content, type, cache_control }` + + A compaction block containing summary of previous context. + + Users should round-trip these blocks from responses to subsequent requests + to maintain context across compaction boundaries. + + When content is None, the block represents a failed compaction. The server + treats these as no-ops. Empty string content is not allowed. + + - `content: string` + + Summary of previously compacted content, or null if compaction failed + + - `type: "compaction"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Content Block Source + +- `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + +### Beta Content Block Source Content + +- `beta_content_block_source_content: BetaTextBlockParam or BetaImageBlockParam` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Context Management Config + +- `beta_context_management_config: object { edits }` + + - `edits: optional array of BetaClearToolUses20250919Edit or BetaClearThinking20251015Edit or BetaCompact20260112Edit` + + List of context management edits to apply + + - `beta_clear_tool_uses_20250919_edit: object { type, clear_at_least, clear_tool_inputs, 3 more }` + + - `type: "clear_tool_uses_20250919"` + + - `clear_at_least: optional object { type, value }` + + Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed. + + - `type: "input_tokens"` + + - `value: number` + + - `clear_tool_inputs: optional boolean or array of string` + + Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) + + - `union_member_0: boolean` + + - `union_member_1: array of string` + + - `exclude_tools: optional array of string` + + Tool names whose uses are preserved from clearing + + - `keep: optional object { type, value }` + + Number of tool uses to retain in the conversation + + - `type: "tool_uses"` + + - `value: number` + + - `trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger` + + Condition that triggers the context management strategy + + - `beta_input_tokens_trigger: object { type, value }` + + - `type: "input_tokens"` + + - `value: number` + + - `beta_tool_uses_trigger: object { type, value }` + + - `type: "tool_uses"` + + - `value: number` + + - `beta_clear_thinking_20251015_edit: object { type, keep }` + + - `type: "clear_thinking_20251015"` + + - `keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"` + + Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. + + - `beta_thinking_turns: object { type, value }` + + - `type: "thinking_turns"` + + - `value: number` + + - `beta_all_thinking_turns: object { type }` + + - `type: "all"` + + - `union_member_2: "all"` + + - `beta_compact_20260112_edit: object { type, instructions, pause_after_compaction, trigger }` + + Automatically compact older context when reaching the configured trigger threshold. + + - `type: "compact_20260112"` + + - `instructions: optional string` + + Additional instructions for summarization. + + - `pause_after_compaction: optional boolean` + + Whether to pause after compaction and return the compaction block to the user. + + - `trigger: optional object { type, value }` + + When to trigger compaction. Defaults to 150000 input tokens. + + - `type: "input_tokens"` + + - `value: number` + +### Beta Context Management Response + +- `beta_context_management_response: object { applied_edits }` + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + +### Beta Count Tokens Context Management Response + +- `beta_count_tokens_context_management_response: object { original_input_tokens }` + + - `original_input_tokens: number` + + The original token count before context management was applied + +### Beta Direct Caller + +- `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + +### Beta Document Block + +- `beta_document_block: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + +### Beta Encrypted Code Execution Result Block + +- `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Beta Encrypted Code Execution Result Block Param + +- `beta_encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Beta File Document Source + +- `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + +### Beta File Image Source + +- `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + +### Beta Image Block Param + +- `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Input JSON Delta + +- `beta_input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + +### Beta Input Tokens Clear At Least + +- `beta_input_tokens_clear_at_least: object { type, value }` + + - `type: "input_tokens"` + + - `value: number` + +### Beta Input Tokens Trigger + +- `beta_input_tokens_trigger: object { type, value }` + + - `type: "input_tokens"` + + - `value: number` + +### Beta Iterations Usage + +- `beta_iterations_usage: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + +### Beta JSON Output Format + +- `beta_json_output_format: object { schema, type }` + + - `schema: map[unknown]` + + The JSON schema of the format + + - `type: "json_schema"` + +### Beta MCP Tool Config + +- `beta_mcp_tool_config: object { defer_loading, enabled }` + + Configuration for a specific tool in an MCP toolset. + + - `defer_loading: optional boolean` + + - `enabled: optional boolean` + +### Beta MCP Tool Default Config + +- `beta_mcp_tool_default_config: object { defer_loading, enabled }` + + Default configuration for tools in an MCP toolset. + + - `defer_loading: optional boolean` + + - `enabled: optional boolean` + +### Beta MCP Tool Result Block + +- `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + +### Beta MCP Tool Use Block + +- `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + +### Beta MCP Tool Use Block Param + +- `beta_mcp_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta MCP Toolset + +- `beta_mcp_toolset: object { mcp_server_name, type, cache_control, 2 more }` + + Configuration for a group of tools from an MCP server. + + Allows configuring enabled status and defer_loading for all tools + from an MCP server, with optional per-tool overrides. + + - `mcp_server_name: string` + + Name of the MCP server to configure tools for + + - `type: "mcp_toolset"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `configs: optional map[BetaMCPToolConfig]` + + Configuration overrides for specific tools, keyed by tool name + + - `defer_loading: optional boolean` + + - `enabled: optional boolean` + + - `default_config: optional object { defer_loading, enabled }` + + Default configuration applied to all tools from this server + + - `defer_loading: optional boolean` + + - `enabled: optional boolean` + +### Beta Memory Tool 20250818 + +- `beta_memory_tool_20250818: object { name, type, allowed_callers, 4 more }` + + - `name: "memory"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "memory_20250818"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Memory Tool 20250818 Command + +- `beta_memory_tool_20250818_command: BetaMemoryTool20250818ViewCommand or BetaMemoryTool20250818CreateCommand or BetaMemoryTool20250818StrReplaceCommand or 3 more` + + - `beta_memory_tool_20250818_view_command: object { command, path, view_range }` + + - `command: "view"` + + Command type identifier + + - `path: string` + + Path to directory or file to view + + - `view_range: optional array of number` + + Optional line range for viewing specific lines + + - `beta_memory_tool_20250818_create_command: object { command, file_text, path }` + + - `command: "create"` + + Command type identifier + + - `file_text: string` + + Content to write to the file + + - `path: string` + + Path where the file should be created + + - `beta_memory_tool_20250818_str_replace_command: object { command, new_str, old_str, path }` + + - `command: "str_replace"` + + Command type identifier + + - `new_str: string` + + Text to replace with + + - `old_str: string` + + Text to search for and replace + + - `path: string` + + Path to the file where text should be replaced + + - `beta_memory_tool_20250818_insert_command: object { command, insert_line, insert_text, path }` + + - `command: "insert"` + + Command type identifier + + - `insert_line: number` + + Line number where text should be inserted + + - `insert_text: string` + + Text to insert at the specified line + + - `path: string` + + Path to the file where text should be inserted + + - `beta_memory_tool_20250818_delete_command: object { command, path }` + + - `command: "delete"` + + Command type identifier + + - `path: string` + + Path to the file or directory to delete + + - `beta_memory_tool_20250818_rename_command: object { command, new_path, old_path }` + + - `command: "rename"` + + Command type identifier + + - `new_path: string` + + New path for the file or directory + + - `old_path: string` + + Current path of the file or directory + +### Beta Memory Tool 20250818 Create Command + +- `beta_memory_tool_20250818_create_command: object { command, file_text, path }` + + - `command: "create"` + + Command type identifier + + - `file_text: string` + + Content to write to the file + + - `path: string` + + Path where the file should be created + +### Beta Memory Tool 20250818 Delete Command + +- `beta_memory_tool_20250818_delete_command: object { command, path }` + + - `command: "delete"` + + Command type identifier + + - `path: string` + + Path to the file or directory to delete + +### Beta Memory Tool 20250818 Insert Command + +- `beta_memory_tool_20250818_insert_command: object { command, insert_line, insert_text, path }` + + - `command: "insert"` + + Command type identifier + + - `insert_line: number` + + Line number where text should be inserted + + - `insert_text: string` + + Text to insert at the specified line + + - `path: string` + + Path to the file where text should be inserted + +### Beta Memory Tool 20250818 Rename Command + +- `beta_memory_tool_20250818_rename_command: object { command, new_path, old_path }` + + - `command: "rename"` + + Command type identifier + + - `new_path: string` + + New path for the file or directory + + - `old_path: string` + + Current path of the file or directory + +### Beta Memory Tool 20250818 Str Replace Command + +- `beta_memory_tool_20250818_str_replace_command: object { command, new_str, old_str, path }` + + - `command: "str_replace"` + + Command type identifier + + - `new_str: string` + + Text to replace with + + - `old_str: string` + + Text to search for and replace + + - `path: string` + + Path to the file where text should be replaced + +### Beta Memory Tool 20250818 View Command + +- `beta_memory_tool_20250818_view_command: object { command, path, view_range }` + + - `command: "view"` + + Command type identifier + + - `path: string` + + Path to directory or file to view + + - `view_range: optional array of number` + + Optional line range for viewing specific lines + +### Beta Message + +- `beta_message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + +### Beta Message Delta Usage + +- `beta_message_delta_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 3 more }` + + - `cache_creation_input_tokens: number` + + The cumulative number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The cumulative number of input tokens read from the cache. + + - `input_tokens: number` + + The cumulative number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The cumulative number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + +### Beta Message Iteration Usage + +- `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + +### Beta Message Param + +- `beta_message_param: object { content, role }` + + - `content: array of BetaContentBlockParam` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_request_document_block: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `beta_search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `beta_thinking_block_param: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block_param: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `beta_request_document_block: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `beta_tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + + - `beta_server_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: array of BetaWebSearchResultBlockParam or BetaWebSearchToolRequestError` + + - `Result Block: array of BetaWebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `beta_web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam` + + - `beta_web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaCodeExecutionToolResultErrorParam or BetaCodeExecutionResultBlockParam or BetaEncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_bash_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam` + + - `beta_bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_text_editor_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam` + + - `beta_text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `beta_text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `beta_text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_tool_search_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam` + + - `beta_tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_mcp_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_request_mcp_tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional string or array of BetaTextBlockParam` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_param_content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `is_error: optional boolean` + + - `beta_container_upload_block_param: object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_compaction_block_param: object { content, type, cache_control }` + + A compaction block containing summary of previous context. + + Users should round-trip these blocks from responses to subsequent requests + to maintain context across compaction boundaries. + + When content is None, the block represents a failed compaction. The server + treats these as no-ops. Empty string content is not allowed. + + - `content: string` + + Summary of previously compacted content, or null if compaction failed + + - `type: "compaction"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `role: "user" or "assistant"` + + - `"user"` + + - `"assistant"` + +### Beta Message Tokens Count + +- `beta_message_tokens_count: object { context_management, input_tokens }` + + - `context_management: object { original_input_tokens }` + + Information about context management applied to the message. + + - `original_input_tokens: number` + + The original token count before context management was applied + + - `input_tokens: number` + + The total number of tokens across the provided list of messages, system prompt, and tools. + +### Beta Metadata + +- `beta_metadata: object { user_id }` + + - `user_id: optional string` + + An external identifier for the user who is associated with the request. + + This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. + +### Beta Output Config + +- `beta_output_config: object { effort, format }` + + - `effort: optional "low" or "medium" or "high" or "max"` + + All possible effort levels. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"max"` + + - `format: optional object { schema, type }` + + A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + - `schema: map[unknown]` + + The JSON schema of the format + + - `type: "json_schema"` + +### Beta Plain Text Source + +- `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + +### Beta Raw Content Block Delta + +- `beta_raw_content_block_delta: BetaTextDelta or BetaInputJSONDelta or BetaCitationsDelta or 3 more` + + - `beta_text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + + - `beta_input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + + - `beta_citations_delta: object { citation, type }` + + - `citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more` + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + + - `beta_thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + + - `beta_signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + + - `beta_compaction_content_block_delta: object { content, type }` + + - `content: string` + + - `type: "compaction_delta"` + +### Beta Raw Content Block Delta Event + +- `beta_raw_content_block_delta_event: object { delta, index, type }` + + - `delta: BetaTextDelta or BetaInputJSONDelta or BetaCitationsDelta or 3 more` + + - `beta_text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + + - `beta_input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + + - `beta_citations_delta: object { citation, type }` + + - `citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more` + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + + - `beta_thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + + - `beta_signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + + - `beta_compaction_content_block_delta: object { content, type }` + + - `content: string` + + - `type: "compaction_delta"` + + - `index: number` + + - `type: "content_block_delta"` + +### Beta Raw Content Block Start Event + +- `beta_raw_content_block_start_event: object { content_block, index, type }` + + - `content_block: BetaTextBlock or BetaThinkingBlock or BetaRedactedThinkingBlock or 12 more` + + Response model for a file uploaded to the container. + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `index: number` + + - `type: "content_block_start"` + +### Beta Raw Content Block Stop Event + +- `beta_raw_content_block_stop_event: object { index, type }` + + - `index: number` + + - `type: "content_block_stop"` + +### Beta Raw Message Delta Event + +- `beta_raw_message_delta_event: object { context_management, delta, type, usage }` + + - `context_management: object { applied_edits }` + + Information about context management strategies applied during the request + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `delta: object { container, stop_details, stop_reason, stop_sequence }` + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + - `type: "message_delta"` + + - `usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 3 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation_input_tokens: number` + + The cumulative number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The cumulative number of input tokens read from the cache. + + - `input_tokens: number` + + The cumulative number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The cumulative number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + +### Beta Raw Message Start Event + +- `beta_raw_message_start_event: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "message_start"` + +### Beta Raw Message Stop Event + +- `beta_raw_message_stop_event: object { type }` + + - `type: "message_stop"` + +### Beta Raw Message Stream Event + +- `beta_raw_message_stream_event: BetaRawMessageStartEvent or BetaRawMessageDeltaEvent or BetaRawMessageStopEvent or 3 more` + + - `beta_raw_message_start_event: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "message_start"` + + - `beta_raw_message_delta_event: object { context_management, delta, type, usage }` + + - `context_management: object { applied_edits }` + + Information about context management strategies applied during the request + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `delta: object { container, stop_details, stop_reason, stop_sequence }` + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + - `type: "message_delta"` + + - `usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 3 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation_input_tokens: number` + + The cumulative number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The cumulative number of input tokens read from the cache. + + - `input_tokens: number` + + The cumulative number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The cumulative number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `beta_raw_message_stop_event: object { type }` + + - `type: "message_stop"` + + - `beta_raw_content_block_start_event: object { content_block, index, type }` + + - `content_block: BetaTextBlock or BetaThinkingBlock or BetaRedactedThinkingBlock or 12 more` + + Response model for a file uploaded to the container. + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `index: number` + + - `type: "content_block_start"` + + - `beta_raw_content_block_delta_event: object { delta, index, type }` + + - `delta: BetaTextDelta or BetaInputJSONDelta or BetaCitationsDelta or 3 more` + + - `beta_text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + + - `beta_input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + + - `beta_citations_delta: object { citation, type }` + + - `citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more` + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + + - `beta_thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + + - `beta_signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + + - `beta_compaction_content_block_delta: object { content, type }` + + - `content: string` + + - `type: "compaction_delta"` + + - `index: number` + + - `type: "content_block_delta"` + + - `beta_raw_content_block_stop_event: object { index, type }` + + - `index: number` + + - `type: "content_block_stop"` + +### Beta Redacted Thinking Block + +- `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + +### Beta Redacted Thinking Block Param + +- `beta_redacted_thinking_block_param: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + +### Beta Refusal Stop Details + +- `beta_refusal_stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + +### Beta Request Document Block + +- `beta_request_document_block: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + +### Beta Request MCP Server Tool Configuration + +- `beta_request_mcp_server_tool_configuration: object { allowed_tools, enabled }` + + - `allowed_tools: optional array of string` + + - `enabled: optional boolean` + +### Beta Request MCP Server URL Definition + +- `beta_request_mcp_server_url_definition: object { name, type, url, 2 more }` + + - `name: string` + + - `type: "url"` + + - `url: string` + + - `authorization_token: optional string` + + - `tool_configuration: optional object { allowed_tools, enabled }` + + - `allowed_tools: optional array of string` + + - `enabled: optional boolean` + +### Beta Request MCP Tool Result Block Param + +- `beta_request_mcp_tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional string or array of BetaTextBlockParam` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_param_content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `is_error: optional boolean` + +### Beta Search Result Block Param + +- `beta_search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + +### Beta Server Tool Caller + +- `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + +### Beta Server Tool Caller 20260120 + +- `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Server Tool Usage + +- `beta_server_tool_usage: object { web_fetch_requests, web_search_requests }` + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + +### Beta Server Tool Use Block + +- `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Server Tool Use Block Param + +- `beta_server_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Signature Delta + +- `beta_signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + +### Beta Skill + +- `beta_skill: object { skill_id, type, version }` + + A skill that was loaded in a container (response model). + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + +### Beta Skill Params + +- `beta_skill_params: object { skill_id, type, version }` + + Specification for a skill to be loaded in a container (request model). + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: optional string` + + Skill version or 'latest' for most recent version + +### Beta Stop Reason + +- `beta_stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + +### Beta Text Block + +- `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + +### Beta Text Block Param + +- `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Beta Text Citation + +- `beta_text_citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more` + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Beta Text Citation Param + +- `beta_text_citation_param: BetaCitationCharLocationParam or BetaCitationPageLocationParam or BetaCitationContentBlockLocationParam or 2 more` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Beta Text Delta + +- `beta_text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + +### Beta Text Editor Code Execution Create Result Block + +- `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + +### Beta Text Editor Code Execution Create Result Block Param + +- `beta_text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + +### Beta Text Editor Code Execution Str Replace Result Block + +- `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + +### Beta Text Editor Code Execution Str Replace Result Block Param + +- `beta_text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + +### Beta Text Editor Code Execution Tool Result Block + +- `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + +### Beta Text Editor Code Execution Tool Result Block Param + +- `beta_text_editor_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam` + + - `beta_text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `beta_text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `beta_text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Text Editor Code Execution Tool Result Error + +- `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + +### Beta Text Editor Code Execution Tool Result Error Param + +- `beta_text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + +### Beta Text Editor Code Execution View Result Block + +- `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + +### Beta Text Editor Code Execution View Result Block Param + +- `beta_text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + +### Beta Thinking Block + +- `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + +### Beta Thinking Block Param + +- `beta_thinking_block_param: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + +### Beta Thinking Config Adaptive + +- `beta_thinking_config_adaptive: object { type, display }` + + - `type: "adaptive"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +### Beta Thinking Config Disabled + +- `beta_thinking_config_disabled: object { type }` + + - `type: "disabled"` + +### Beta Thinking Config Enabled + +- `beta_thinking_config_enabled: object { budget_tokens, type, display }` + + - `budget_tokens: number` + + Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. + + Must be ≥1024 and less than `max_tokens`. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `type: "enabled"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +### Beta Thinking Config Param + +- `beta_thinking_config_param: BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigAdaptive` + + Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `beta_thinking_config_enabled: object { budget_tokens, type, display }` + + - `budget_tokens: number` + + Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. + + Must be ≥1024 and less than `max_tokens`. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `type: "enabled"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + + - `beta_thinking_config_disabled: object { type }` + + - `type: "disabled"` + + - `beta_thinking_config_adaptive: object { type, display }` + + - `type: "adaptive"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +### Beta Thinking Delta + +- `beta_thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + +### Beta Thinking Turns + +- `beta_thinking_turns: object { type, value }` + + - `type: "thinking_turns"` + + - `value: number` + +### Beta Tool + +- `beta_tool: object { input_schema, name, allowed_callers, 7 more }` + + - `input_schema: object { type, properties, required }` + + [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + + This defines the shape of the `input` that your tool accepts and that the model will produce. + + - `type: "object"` + + - `properties: optional map[unknown]` + + - `required: optional array of string` + + - `name: string` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `description: optional string` + + Description of what this tool does. + + Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + + - `eager_input_streaming: optional boolean` + + Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `type: optional "custom"` + + - `"custom"` + +### Beta Tool Bash 20241022 + +- `beta_tool_bash_20241022: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20241022"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Bash 20250124 + +- `beta_tool_bash_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Choice + +- `beta_tool_choice: BetaToolChoiceAuto or BetaToolChoiceAny or BetaToolChoiceTool or BetaToolChoiceNone` + + How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + + - `beta_tool_choice_auto: object { type, disable_parallel_tool_use }` + + The model will automatically decide whether to use tools. + + - `type: "auto"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output at most one tool use. + + - `beta_tool_choice_any: object { type, disable_parallel_tool_use }` + + The model will use any available tools. + + - `type: "any"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + + - `beta_tool_choice_tool: object { name, type, disable_parallel_tool_use }` + + The model will use the specified tool with `tool_choice.name`. + + - `name: string` + + The name of the tool to use. + + - `type: "tool"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + + - `beta_tool_choice_none: object { type }` + + The model will not be allowed to use tools. + + - `type: "none"` + +### Beta Tool Choice Any + +- `beta_tool_choice_any: object { type, disable_parallel_tool_use }` + + The model will use any available tools. + + - `type: "any"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + +### Beta Tool Choice Auto + +- `beta_tool_choice_auto: object { type, disable_parallel_tool_use }` + + The model will automatically decide whether to use tools. + + - `type: "auto"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output at most one tool use. + +### Beta Tool Choice None + +- `beta_tool_choice_none: object { type }` + + The model will not be allowed to use tools. + + - `type: "none"` + +### Beta Tool Choice Tool + +- `beta_tool_choice_tool: object { name, type, disable_parallel_tool_use }` + + The model will use the specified tool with `tool_choice.name`. + + - `name: string` + + The name of the tool to use. + + - `type: "tool"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + +### Beta Tool Computer Use 20241022 + +- `beta_tool_computer_use_20241022: object { display_height_px, display_width_px, name, 7 more }` + + - `display_height_px: number` + + The height of the display in pixels. + + - `display_width_px: number` + + The width of the display in pixels. + + - `name: "computer"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "computer_20241022"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `display_number: optional number` + + The X11 display number (e.g. 0, 1) for the display. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Computer Use 20250124 + +- `beta_tool_computer_use_20250124: object { display_height_px, display_width_px, name, 7 more }` + + - `display_height_px: number` + + The height of the display in pixels. + + - `display_width_px: number` + + The width of the display in pixels. + + - `name: "computer"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "computer_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `display_number: optional number` + + The X11 display number (e.g. 0, 1) for the display. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Computer Use 20251124 + +- `beta_tool_computer_use_20251124: object { display_height_px, display_width_px, name, 8 more }` + + - `display_height_px: number` + + The height of the display in pixels. + + - `display_width_px: number` + + The width of the display in pixels. + + - `name: "computer"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "computer_20251124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `display_number: optional number` + + The X11 display number (e.g. 0, 1) for the display. + + - `enable_zoom: optional boolean` + + Whether to enable an action to take a zoomed-in screenshot of the screen. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Reference Block + +- `beta_tool_reference_block: object { tool_name, type }` + + - `tool_name: string` + + - `type: "tool_reference"` + +### Beta Tool Reference Block Param + +- `beta_tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Tool Result Block Param + +- `beta_tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `beta_request_document_block: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `beta_tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + +### Beta Tool Search Tool Bm25 20251119 + +- `beta_tool_search_tool_bm25_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_bm25"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + + - `"tool_search_tool_bm25"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Search Tool Regex 20251119 + +- `beta_tool_search_tool_regex_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_regex"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + + - `"tool_search_tool_regex"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Search Tool Result Block + +- `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + +### Beta Tool Search Tool Result Block Param + +- `beta_tool_search_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam` + + - `beta_tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Tool Search Tool Result Error + +- `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + +### Beta Tool Search Tool Result Error Param + +- `beta_tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + +### Beta Tool Search Tool Search Result Block + +- `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + +### Beta Tool Search Tool Search Result Block Param + +- `beta_tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + +### Beta Tool Text Editor 20241022 + +- `beta_tool_text_editor_20241022: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20241022"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Text Editor 20250124 + +- `beta_tool_text_editor_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Text Editor 20250429 + +- `beta_tool_text_editor_20250429: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250429"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Text Editor 20250728 + +- `beta_tool_text_editor_20250728: object { name, type, allowed_callers, 5 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250728"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `max_characters: optional number` + + Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Union + +- `beta_tool_union: BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 19 more` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `beta_tool: object { input_schema, name, allowed_callers, 7 more }` + + - `input_schema: object { type, properties, required }` + + [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + + This defines the shape of the `input` that your tool accepts and that the model will produce. + + - `type: "object"` + + - `properties: optional map[unknown]` + + - `required: optional array of string` + + - `name: string` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `description: optional string` + + Description of what this tool does. + + Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + + - `eager_input_streaming: optional boolean` + + Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `type: optional "custom"` + + - `"custom"` + + - `beta_tool_bash_20241022: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20241022"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_bash_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_code_execution_tool_20250522: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250522"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_code_execution_tool_20250825: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250825"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_code_execution_tool_20260120: object { name, type, allowed_callers, 3 more }` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20260120"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_computer_use_20241022: object { display_height_px, display_width_px, name, 7 more }` + + - `display_height_px: number` + + The height of the display in pixels. + + - `display_width_px: number` + + The width of the display in pixels. + + - `name: "computer"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "computer_20241022"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `display_number: optional number` + + The X11 display number (e.g. 0, 1) for the display. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_memory_tool_20250818: object { name, type, allowed_callers, 4 more }` + + - `name: "memory"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "memory_20250818"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_computer_use_20250124: object { display_height_px, display_width_px, name, 7 more }` + + - `display_height_px: number` + + The height of the display in pixels. + + - `display_width_px: number` + + The width of the display in pixels. + + - `name: "computer"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "computer_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `display_number: optional number` + + The X11 display number (e.g. 0, 1) for the display. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_text_editor_20241022: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20241022"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_computer_use_20251124: object { display_height_px, display_width_px, name, 8 more }` + + - `display_height_px: number` + + The height of the display in pixels. + + - `display_width_px: number` + + The width of the display in pixels. + + - `name: "computer"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "computer_20251124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `display_number: optional number` + + The X11 display number (e.g. 0, 1) for the display. + + - `enable_zoom: optional boolean` + + Whether to enable an action to take a zoomed-in screenshot of the screen. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_text_editor_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_text_editor_20250429: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250429"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_text_editor_20250728: object { name, type, allowed_callers, 5 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250728"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `max_characters: optional number` + + Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_web_search_tool_20250305: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20250305"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `beta_web_fetch_tool_20250910: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20250910"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_web_search_tool_20260209: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `beta_web_fetch_tool_20260209: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_web_fetch_tool_20260309: object { name, type, allowed_callers, 9 more }` + + Web fetch tool with use_cache parameter for bypassing cached content. + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260309"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `use_cache: optional boolean` + + Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. + + - `beta_tool_search_tool_bm25_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_bm25"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + + - `"tool_search_tool_bm25"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_search_tool_regex_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_regex"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + + - `"tool_search_tool_regex"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_mcp_toolset: object { mcp_server_name, type, cache_control, 2 more }` + + Configuration for a group of tools from an MCP server. + + Allows configuring enabled status and defer_loading for all tools + from an MCP server, with optional per-tool overrides. + + - `mcp_server_name: string` + + Name of the MCP server to configure tools for + + - `type: "mcp_toolset"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `configs: optional map[BetaMCPToolConfig]` + + Configuration overrides for specific tools, keyed by tool name + + - `defer_loading: optional boolean` + + - `enabled: optional boolean` + + - `default_config: optional object { defer_loading, enabled }` + + Default configuration applied to all tools from this server + + - `defer_loading: optional boolean` + + - `enabled: optional boolean` + +### Beta Tool Use Block + +- `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Tool Use Block Param + +- `beta_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Tool Uses Keep + +- `beta_tool_uses_keep: object { type, value }` + + - `type: "tool_uses"` + + - `value: number` + +### Beta Tool Uses Trigger + +- `beta_tool_uses_trigger: object { type, value }` + + - `type: "tool_uses"` + + - `value: number` + +### Beta URL Image Source + +- `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + +### Beta URL PDF Source + +- `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + +### Beta Usage + +- `beta_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + +### Beta User Location + +- `beta_user_location: object { type, city, country, 2 more }` + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + +### Beta Web Fetch Block + +- `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + +### Beta Web Fetch Block Param + +- `beta_web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + +### Beta Web Fetch Tool 20250910 + +- `beta_web_fetch_tool_20250910: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20250910"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Web Fetch Tool 20260209 + +- `beta_web_fetch_tool_20260209: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Web Fetch Tool 20260309 + +- `beta_web_fetch_tool_20260309: object { name, type, allowed_callers, 9 more }` + + Web fetch tool with use_cache parameter for bypassing cached content. + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260309"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `use_cache: optional boolean` + + Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. + +### Beta Web Fetch Tool Result Block + +- `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Web Fetch Tool Result Block Param + +- `beta_web_fetch_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam` + + - `beta_web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Web Fetch Tool Result Error Block + +- `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + +### Beta Web Fetch Tool Result Error Block Param + +- `beta_web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + +### Beta Web Fetch Tool Result Error Code + +- `beta_web_fetch_tool_result_error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + +### Beta Web Search Result Block + +- `beta_web_search_result_block: object { encrypted_content, page_age, title, 2 more }` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + +### Beta Web Search Result Block Param + +- `beta_web_search_result_block_param: object { encrypted_content, title, type, 2 more }` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + +### Beta Web Search Tool 20250305 + +- `beta_web_search_tool_20250305: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20250305"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + +### Beta Web Search Tool 20260209 + +- `beta_web_search_tool_20260209: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + +### Beta Web Search Tool Request Error + +- `beta_web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + +### Beta Web Search Tool Result Block + +- `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Web Search Tool Result Block Content + +- `beta_web_search_tool_result_block_content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + +### Beta Web Search Tool Result Block Param + +- `beta_web_search_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: array of BetaWebSearchResultBlockParam or BetaWebSearchToolRequestError` + + - `Result Block: array of BetaWebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `beta_web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Web Search Tool Result Block Param Content + +- `beta_web_search_tool_result_block_param_content: array of BetaWebSearchResultBlockParam or BetaWebSearchToolRequestError` + + - `Result Block: array of BetaWebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `beta_web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + +### Beta Web Search Tool Result Error + +- `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + +### Beta Web Search Tool Result Error Code + +- `beta_web_search_tool_result_error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + +# Batches + +## Create + +`$ ant beta:messages:batches create` + +**post** `/v1/messages/batches` + +Send a batch of Message creation requests. + +The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--request: array of object { custom_id, params }` + + Body param: List of requests for prompt completion. Each is an individual request to create a Message. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant beta:messages:batches create \ + --api-key my-anthropic-api-key \ + --request '{custom_id: my-custom-id-1, params: {max_tokens: 1024, messages: [{content: [{text: x, type: text}], role: user}], model: claude-opus-4-6}}' +``` + +## Retrieve + +`$ ant beta:messages:batches retrieve` + +**get** `/v1/messages/batches/{message_batch_id}` + +This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant beta:messages:batches retrieve \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## List + +`$ ant beta:messages:batches list` + +**get** `/v1/messages/batches` + +List all Message Batches within a Workspace. Most recently created batches are returned first. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListResponse_MessageBatch_: object { data, first_id, has_more, last_id }` + + - `data: array of BetaMessageBatch` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant beta:messages:batches list \ + --api-key my-anthropic-api-key +``` + +## Cancel + +`$ ant beta:messages:batches cancel` + +**post** `/v1/messages/batches/{message_batch_id}/cancel` + +Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. + +The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant beta:messages:batches cancel \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Delete + +`$ ant beta:messages:batches delete` + +**delete** `/v1/messages/batches/{message_batch_id}` + +Delete a Message Batch. + +Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Example + +```cli +ant beta:messages:batches delete \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Results + +`$ ant beta:messages:batches results` + +**get** `/v1/messages/batches/{message_batch_id}/results` + +Streams the results of a Message Batch as a `.jsonl` file. + +Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` + + - `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Example + +```cli +ant beta:messages:batches results \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Domain Types + +### Beta Deleted Message Batch + +- `beta_deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Beta Message Batch + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Beta Message Batch Canceled Result + +- `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + +### Beta Message Batch Errored Result + +- `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + +### Beta Message Batch Expired Result + +- `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Beta Message Batch Individual Response + +- `beta_message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` + + - `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Beta Message Batch Request Counts + +- `beta_message_batch_request_counts: object { canceled, errored, expired, 2 more }` + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + +### Beta Message Batch Result + +- `beta_message_batch_result: BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` + + - `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Beta Message Batch Succeeded Result + +- `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` + +# Agents + +## Create + +`$ ant beta:agents create` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `--model: BetaManagedAgentsModelConfigParams` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + +- `--name: string` + + Body param: Human-readable name for the agent. 1-256 characters. + +- `--description: optional string` + + Body param: Description of what the agent does. Up to 2048 characters. + +- `--mcp-server: optional array of BetaManagedAgentsURLMCPServerParams` + + Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + +- `--skill: optional array of BetaManagedAgentsSkillParams` + + Body param: Skills available to the agent. Maximum 20. + +- `--system: optional string` + + Body param: System prompt for the agent. Up to 100,000 characters. + +- `--tool: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` + + Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```cli +ant beta:agents create \ + --api-key my-anthropic-api-key \ + --model '{id: claude-opus-4-6}' \ + --name 'My First Agent' +``` + +## List + +`$ ant beta:agents list` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `--created-at-gte: optional string` + + Query param: Return agents created at or after this time (inclusive). + +- `--created-at-lte: optional string` + + Query param: Return agents created at or before this time (inclusive). + +- `--include-archived: optional boolean` + + Query param: Include archived agents in results. Defaults to false. + +- `--limit: optional number` + + Query param: Maximum results per page. Default 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination cursor from a previous response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListAgents: object { data, next_page }` + + Paginated list of agents. + + - `data: optional array of BetaManagedAgentsAgent` + + List of agents. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:agents list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant beta:agents retrieve` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `--agent-id: string` + + Path param: Path parameter agent_id + +- `--version: optional number` + + Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```cli +ant beta:agents retrieve \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP +``` + +## Update + +`$ ant beta:agents update` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `--agent-id: string` + + Path param: Path parameter agent_id + +- `--version: number` + + Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + +- `--description: optional string` + + Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + +- `--mcp-server: optional array of BetaManagedAgentsURLMCPServerParams` + + Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + +- `--model: optional BetaManagedAgentsModelConfigParams` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + +- `--name: optional string` + + Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + +- `--skill: optional array of BetaManagedAgentsSkillParams` + + Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + +- `--system: optional string` + + Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + +- `--tool: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` + + Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```cli +ant beta:agents update \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP \ + --version 1 +``` + +## Archive + +`$ ant beta:agents archive` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `--agent-id: string` + + Path parameter agent_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```cli +ant beta:agents archive \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `beta_managed_agents_agent_tool_config: object { enabled, name, permission_policy }` + + Configuration for a specific agent tool. + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Tool Config Params + +- `beta_managed_agents_agent_tool_config_params: object { name, enabled, permission_policy }` + + Configuration override for a specific tool within a toolset. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config + +- `beta_managed_agents_agent_toolset_default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `beta_managed_agents_agent_toolset_default_config_params: object { enabled, permission_policy }` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset20260401 + +- `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `beta_managed_agents_agent_toolset20260401_params: object { type, configs, default_config }` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` + + Per-tool configuration overrides. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional object { enabled, permission_policy }` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Always Allow Policy + +- `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + +### Beta Managed Agents Always Ask Policy + +- `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Anthropic Skill + +- `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + +### Beta Managed Agents Anthropic Skill Params + +- `beta_managed_agents_anthropic_skill_params: object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + +### Beta Managed Agents Custom Skill Params + +- `beta_managed_agents_custom_skill_params: object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + +### Beta Managed Agents Custom Tool Input Schema + +- `beta_managed_agents_custom_tool_input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + +### Beta Managed Agents Custom Tool Params + +- `beta_managed_agents_custom_tool_params: object { description, input_schema, name, type }` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + +### Beta Managed Agents MCP Server URL Definition + +- `beta_managed_agents_mcp_server_url_definition: object { name, type, url }` + + URL-based MCP server connection as returned in API responses. + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + +### Beta Managed Agents MCP Tool Config + +- `beta_managed_agents_mcp_tool_config: object { enabled, name, permission_policy }` + + Resolved configuration for a specific MCP tool. + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Tool Config Params + +- `beta_managed_agents_mcp_tool_config_params: object { name, enabled, permission_policy }` + + Configuration override for a specific MCP tool. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset + +- `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + +### Beta Managed Agents MCP Toolset Default Config + +- `beta_managed_agents_mcp_toolset_default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `beta_managed_agents_mcp_toolset_default_config_params: object { enabled, permission_policy }` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Params + +- `beta_managed_agents_mcp_toolset_params: object { mcp_server_name, type, configs, default_config }` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional object { enabled, permission_policy }` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Model Config + +- `beta_managed_agents_model_config: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Model Config Params + +- `beta_managed_agents_model_config_params: object { id, speed }` + + An object that defines additional configuration control over model use + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Skill Params + +- `beta_managed_agents_skill_params: BetaManagedAgentsAnthropicSkillParams or BetaManagedAgentsCustomSkillParams` + + Skill to load in the session container. + + - `beta_managed_agents_anthropic_skill_params: object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + + - `beta_managed_agents_custom_skill_params: object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `beta_managed_agents_url_mcp_server_params: object { name, type, url }` + + URL-based MCP server connection. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + +# Versions + +## List + +`$ ant beta:agents:versions list` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `--agent-id: string` + + Path param: Path parameter agent_id + +- `--limit: optional number` + + Query param: Maximum results per page. Default 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination cursor. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListAgentVersions: object { data, next_page }` + + Paginated list of agent versions. + + - `data: optional array of BetaManagedAgentsAgent` + + Agent versions. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:agents:versions list \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP +``` + +# Environments + +## Create + +`$ ant beta:environments create` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `--name: string` + + Body param: Human-readable name for the environment + +- `--config: optional object { type, networking, packages }` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + +- `--description: optional string` + + Body param: Optional description of the environment + +- `--metadata: optional map[string]` + + Body param: User-provided metadata key-value pairs + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```cli +ant beta:environments create \ + --api-key my-anthropic-api-key \ + --name python-data-analysis +``` + +## List + +`$ ant beta:environments list` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `--include-archived: optional boolean` + + Query param: Include archived environments in the response + +- `--limit: optional number` + + Query param: Maximum number of environments to return + +- `--page: optional string` + + Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaEnvironmentListResponse: object { data, next_page }` + + Response when listing environments. + + This response model uses opaque cursor-based pagination. Use the `page` + query parameter with the value from `next_page` to fetch the next page. + + - `data: array of BetaEnvironment` + + List of environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + + - `next_page: string` + + Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request. + +### Example + +```cli +ant beta:environments list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant beta:environments retrieve` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `--environment-id: string` + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```cli +ant beta:environments retrieve \ + --api-key my-anthropic-api-key \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` + +## Update + +`$ ant beta:environments update` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `--environment-id: string` + + Path param + +- `--config: optional object { type, networking, packages }` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + +- `--description: optional string` + + Body param: Updated description of the environment + +- `--metadata: optional map[string]` + + Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + +- `--name: optional string` + + Body param: Updated name for the environment + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```cli +ant beta:environments update \ + --api-key my-anthropic-api-key \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` + +## Delete + +`$ ant beta:environments delete` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `--environment-id: string` + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment_delete_response: object { id, type }` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + +### Example + +```cli +ant beta:environments delete \ + --api-key my-anthropic-api-key \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` + +## Archive + +`$ ant beta:environments archive` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `--environment-id: string` + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```cli +ant beta:environments archive \ + --api-key my-anthropic-api-key \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` + +## Domain Types + +### Beta Cloud Config + +- `beta_cloud_config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + +### Beta Cloud Config Params + +- `beta_cloud_config_params: object { type, networking, packages }` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network_params: object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + + - `packages: optional object { apt, cargo, gem, 4 more }` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +### Beta Environment + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `beta_environment_delete_response: object { id, type }` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + +### Beta Limited Network + +- `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + +### Beta Limited Network Params + +- `beta_limited_network_params: object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + +### Beta Packages + +- `beta_packages: object { apt, cargo, gem, 4 more }` + + Packages (and their versions) available in this environment. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +### Beta Packages Params + +- `beta_packages_params: object { apt, cargo, gem, 4 more }` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +### Beta Unrestricted Network + +- `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + +# Sessions + +## Create + +`$ ant beta:sessions create` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `--agent: string or BetaManagedAgentsAgentParams` + + Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + +- `--environment-id: string` + + Body param: ID of the `environment` defining the container configuration for this session. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata attached to the session. + +- `--resource: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams` + + Body param: Resources (e.g. repositories, files) to mount into the session's container. + +- `--title: optional string` + + Body param: Human-readable session title. + +- `--vault-id: optional array of string` + + Body param: Vault IDs for stored credentials the agent can use during the session. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```cli +ant beta:sessions create \ + --api-key my-anthropic-api-key \ + --agent agent_011CZkYpogX7uDKUyvBTophP \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` + +## List + +`$ ant beta:sessions list` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `--agent-id: optional string` + + Query param: Filter sessions created with this agent ID. + +- `--agent-version: optional number` + + Query param: Filter by agent version. Only applies when agent_id is also set. + +- `--created-at-gt: optional string` + + Query param: Return sessions created after this time (exclusive). + +- `--created-at-gte: optional string` + + Query param: Return sessions created at or after this time (inclusive). + +- `--created-at-lt: optional string` + + Query param: Return sessions created before this time (exclusive). + +- `--created-at-lte: optional string` + + Query param: Return sessions created at or before this time (inclusive). + +- `--include-archived: optional boolean` + + Query param: When true, includes archived sessions. Default: false (exclude archived). + +- `--limit: optional number` + + Query param: Maximum number of results to return. + +- `--order: optional "asc" or "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). + +- `--page: optional string` + + Query param: Opaque pagination cursor from a previous response's next_page. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListSessions: object { data, next_page }` + + Paginated list of sessions. + + - `data: optional array of BetaManagedAgentsSession` + + List of sessions. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:sessions list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant beta:sessions retrieve` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```cli +ant beta:sessions retrieve \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Update + +`$ ant beta:sessions update` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + +- `--title: optional string` + + Body param: Human-readable session title. + +- `--vault-id: optional array of string` + + Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```cli +ant beta:sessions update \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Delete + +`$ ant beta:sessions delete` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_deleted_session: object { id, type }` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Example + +```cli +ant beta:sessions delete \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Archive + +`$ ant beta:sessions archive` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```cli +ant beta:sessions archive \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `beta_managed_agents_agent_params: object { id, type, version }` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: string` + + The `agent` ID. + + - `type: "agent"` + + - `"agent"` + + - `version: optional number` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + +### Beta Managed Agents Cache Creation Usage + +- `beta_managed_agents_cache_creation_usage: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Deleted Session + +- `beta_managed_agents_deleted_session: object { id, type }` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Beta Managed Agents File Resource Params + +- `beta_managed_agents_file_resource_params: object { file_id, type, mount_path }` + + Mount a file uploaded via the Files API into the session. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `beta_managed_agents_github_repository_resource_params: object { authorization_token, type, url, 2 more }` + + Mount a GitHub repository into the session's container. + + - `authorization_token: string` + + GitHub authorization token used to clone the repository. + + - `type: "github_repository"` + + - `"github_repository"` + + - `url: string` + + Github URL of the repository + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `beta_managed_agents_session_agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + +### Beta Managed Agents Session Stats + +- `beta_managed_agents_session_stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `beta_managed_agents_session_usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + +# Events + +## List + +`$ ant beta:sessions:events list` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--limit: optional number` + + Query param: Query parameter for limit + +- `--order: optional "asc" or "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + +- `--page: optional string` + + Query param: Opaque pagination cursor from a previous response's next_page. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListSessionEvents: object { data, next_page }` + + Paginated list of events for a `session`. + + - `data: optional array of BetaManagedAgentsSessionEvent` + + Events for the session, ordered by `created_at`. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:sessions:events list \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Send + +`$ ant beta:sessions:events send` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--event: array of BetaManagedAgentsEventParams` + + Body param: Events to send to the `session`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_send_session_events: object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:events send \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --event "{content: [{text: 'Where is my order #1234?', type: text}], type: user.message}" +``` + +## Stream + +`$ ant beta:sessions:events stream` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_stream_session_events: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```cli +ant beta:sessions:events stream \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Agent Message Event + +- `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Base64 Document Source + +- `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Base64 Image Source + +- `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Billing Error + +- `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + +### Beta Managed Agents Document Block + +- `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + +### Beta Managed Agents Event Params + +- `beta_managed_agents_event_params: BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserInterruptEventParams or BetaManagedAgentsUserToolConfirmationEventParams or BetaManagedAgentsUserCustomToolResultEventParams` + + Union type for event parameters that can be sent to a session. + + - `beta_managed_agents_user_message_event_params: object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `beta_managed_agents_user_interrupt_event_params: object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `beta_managed_agents_user_tool_confirmation_event_params: object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `beta_managed_agents_user_custom_tool_result_event_params: object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents File Image Source + +- `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents Image Block + +- `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Retry Status Exhausted + +- `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + +### Beta Managed Agents Send Session Events + +- `beta_managed_agents_send_session_events: object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + +### Beta Managed Agents Session Error Event + +- `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + +### Beta Managed Agents Session Event + +- `beta_managed_agents_session_event: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Union type for all event types in a session. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `beta_managed_agents_span_model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Stream Session Events + +- `beta_managed_agents_stream_session_events: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Text Block + +- `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Unknown Error + +- `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + +### Beta Managed Agents URL Document Source + +- `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `beta_managed_agents_user_custom_tool_result_event_params: object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `beta_managed_agents_user_interrupt_event_params: object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `beta_managed_agents_user_message_event_params: object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `beta_managed_agents_user_tool_confirmation_event_params: object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`$ ant beta:sessions:resources add` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--file-id: string` + + Body param: ID of a previously uploaded file. + +- `--type: "file"` + + Body param + +- `--mount-path: optional string` + + Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:resources add \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --file-id file_011CNha8iCJcU1wXNR6q4V8w \ + --type file +``` + +## List + +`$ ant beta:sessions:resources list` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--limit: optional number` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `--page: optional string` + + Query param: Opaque cursor from a previous response's next_page field. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListSessionResources: object { data, next_page }` + + Paginated list of resources attached to a session. + + - `data: array of BetaManagedAgentsSessionResource` + + Resources for the session, ordered by `created_at`. + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:sessions:resources list \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Retrieve + +`$ ant beta:sessions:resources retrieve` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--resource-id: string` + + Path param: Path parameter resource_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSessionResourceGetResponse: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The requested session resource. + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:resources retrieve \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht +``` + +## Update + +`$ ant beta:sessions:resources update` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--resource-id: string` + + Path param: Path parameter resource_id + +- `--authorization-token: string` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSessionResourceUpdateResponse: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The updated session resource. + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:resources update \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht \ + --authorization-token ghp_exampletoken +``` + +## Delete + +`$ ant beta:sessions:resources delete` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--resource-id: string` + + Path param: Path parameter resource_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_delete_session_resource: object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Example + +```cli +ant beta:sessions:resources delete \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `beta_managed_agents_delete_session_resource: object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Session Resource + +- `beta_managed_agents_session_resource: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +# Vaults + +## Create + +`$ ant beta:vaults create` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `--display-name: string` + + Body param: Human-readable name for the vault. 1-255 characters. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata to attach to the vault. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:vaults create \ + --api-key my-anthropic-api-key \ + --display-name 'Example vault' +``` + +## List + +`$ ant beta:vaults list` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `--include-archived: optional boolean` + + Query param: Whether to include archived vaults in the results. + +- `--limit: optional number` + + Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination token from a previous `list_vaults` response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListVaultsResponse: object { data, next_page }` + + Response containing a paginated list of vaults. + + - `data: optional array of BetaManagedAgentsVault` + + List of vaults. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```cli +ant beta:vaults list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant beta:vaults retrieve` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `--vault-id: string` + + Path parameter vault_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:vaults retrieve \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` + +## Update + +`$ ant beta:vaults update` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--display-name: optional string` + + Body param: Updated human-readable name for the vault. 1-255 characters. + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:vaults update \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` + +## Delete + +`$ ant beta:vaults delete` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `--vault-id: string` + + Path parameter vault_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_deleted_vault: object { id, type }` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Example + +```cli +ant beta:vaults delete \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` + +## Archive + +`$ ant beta:vaults archive` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `--vault-id: string` + + Path parameter vault_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:vaults archive \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `beta_managed_agents_deleted_vault: object { id, type }` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Beta Managed Agents Vault + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`$ ant beta:vaults:credentials create` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--auth: BetaManagedAgentsMCPOAuthCreateParams or BetaManagedAgentsStaticBearerCreateParams` + + Body param: Authentication details for creating a credential. + +- `--display-name: optional string` + + Body param: Human-readable name for the credential. Up to 255 characters. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata to attach to the credential. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials create \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --auth '{token: bearer_exampletoken, mcp_server_url: https://example-server.modelcontextprotocol.io/sse, type: static_bearer}' +``` + +## List + +`$ ant beta:vaults:credentials list` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--include-archived: optional boolean` + + Query param: Whether to include archived credentials in the results. + +- `--limit: optional number` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination token from a previous `list_credentials` response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListCredentialsResponse: object { data, next_page }` + + Response containing a paginated list of credentials. + + - `data: optional array of BetaManagedAgentsCredential` + + List of credentials. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + + - `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```cli +ant beta:vaults:credentials list \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` + +## Retrieve + +`$ ant beta:vaults:credentials retrieve` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials retrieve \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` + +## Update + +`$ ant beta:vaults:credentials update` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--auth: optional BetaManagedAgentsMCPOAuthUpdateParams or BetaManagedAgentsStaticBearerUpdateParams` + + Body param: Updated authentication details for a credential. + +- `--display-name: optional string` + + Body param: Updated human-readable name for the credential. 1-255 characters. + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials update \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` + +## Delete + +`$ ant beta:vaults:credentials delete` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_deleted_credential: object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Example + +```cli +ant beta:vaults:credentials delete \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` + +## Archive + +`$ ant beta:vaults:credentials archive` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials archive \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `beta_managed_agents_deleted_credential: object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `beta_managed_agents_mcp_oauth_create_params: object { access_token, mcp_server_url, type, 2 more }` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, refresh_token, token_endpoint, 3 more }` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_param: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_param: object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_param: object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `beta_managed_agents_mcp_oauth_refresh_params: object { client_id, refresh_token, token_endpoint, 3 more }` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_param: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_param: object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_param: object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `beta_managed_agents_mcp_oauth_refresh_response: object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `beta_managed_agents_mcp_oauth_refresh_update_params: object { refresh_token, scope, token_endpoint_auth }` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `beta_managed_agents_token_endpoint_auth_basic_update_param: object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `beta_managed_agents_token_endpoint_auth_post_update_param: object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `beta_managed_agents_mcp_oauth_update_params: object { type, access_token, expires_at, refresh }` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token: optional string` + + Updated OAuth access token. + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { refresh_token, scope, token_endpoint_auth }` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `beta_managed_agents_token_endpoint_auth_basic_update_param: object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `beta_managed_agents_token_endpoint_auth_post_update_param: object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `beta_managed_agents_static_bearer_create_params: object { token, mcp_server_url, type }` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `beta_managed_agents_static_bearer_update_params: object { type, token }` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token: optional string` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `beta_managed_agents_token_endpoint_auth_basic_param: object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `beta_managed_agents_token_endpoint_auth_basic_update_param: object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `beta_managed_agents_token_endpoint_auth_none_param: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `beta_managed_agents_token_endpoint_auth_post_param: object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `beta_managed_agents_token_endpoint_auth_post_update_param: object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +# Files + +## Upload + +`$ ant beta:files upload` + +**post** `/v1/files` + +Upload File + +### Parameters + +- `--file: string` + + Body param: The file to upload + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `file_metadata: object { id, created_at, filename, 5 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: string` + + RFC 3339 datetime string representing when the file was created. + + - `filename: string` + + Original filename of the uploaded file. + + - `mime_type: string` + + MIME type of the file. + + - `size_bytes: number` + + Size of the file in bytes. + + - `type: "file"` + + Object type. + + For files, this is always `"file"`. + + - `downloadable: optional boolean` + + Whether the file can be downloaded. + + - `scope: optional object { id, type }` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + +### Example + +```cli +ant beta:files upload \ + --api-key my-anthropic-api-key \ + --file 'Example data' +``` + +## List + +`$ ant beta:files list` + +**get** `/v1/files` + +List Files + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--scope-id: optional string` + + Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaFileListResponse: object { data, first_id, has_more, last_id }` + + - `data: array of FileMetadata` + + List of file metadata objects. + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: string` + + RFC 3339 datetime string representing when the file was created. + + - `filename: string` + + Original filename of the uploaded file. + + - `mime_type: string` + + MIME type of the file. + + - `size_bytes: number` + + Size of the file in bytes. + + - `type: "file"` + + Object type. + + For files, this is always `"file"`. + + - `downloadable: optional boolean` + + Whether the file can be downloaded. + + - `scope: optional object { id, type }` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `first_id: optional string` + + ID of the first file in this page of results. + + - `has_more: optional boolean` + + Whether there are more results available. + + - `last_id: optional string` + + ID of the last file in this page of results. + +### Example + +```cli +ant beta:files list \ + --api-key my-anthropic-api-key +``` + +## Download + +`$ ant beta:files download` + +**get** `/v1/files/{file_id}/content` + +Download File + +### Parameters + +- `--file-id: string` + + ID of the File. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `unnamed_schema_0: file path` + +### Example + +```cli +ant beta:files download \ + --api-key my-anthropic-api-key \ + --file-id file_id +``` + +## Retrieve Metadata + +`$ ant beta:files retrieve-metadata` + +**get** `/v1/files/{file_id}` + +Get File Metadata + +### Parameters + +- `--file-id: string` + + ID of the File. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `file_metadata: object { id, created_at, filename, 5 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: string` + + RFC 3339 datetime string representing when the file was created. + + - `filename: string` + + Original filename of the uploaded file. + + - `mime_type: string` + + MIME type of the file. + + - `size_bytes: number` + + Size of the file in bytes. + + - `type: "file"` + + Object type. + + For files, this is always `"file"`. + + - `downloadable: optional boolean` + + Whether the file can be downloaded. + + - `scope: optional object { id, type }` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + +### Example + +```cli +ant beta:files retrieve-metadata \ + --api-key my-anthropic-api-key \ + --file-id file_id +``` + +## Delete + +`$ ant beta:files delete` + +**delete** `/v1/files/{file_id}` + +Delete File + +### Parameters + +- `--file-id: string` + + ID of the File. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `deleted_file: object { id, type }` + + - `id: string` + + ID of the deleted file. + + - `type: optional "file_deleted"` + + Deleted object type. + + For file deletion, this is always `"file_deleted"`. + + - `"file_deleted"` + +### Example + +```cli +ant beta:files delete \ + --api-key my-anthropic-api-key \ + --file-id file_id +``` + +## Domain Types + +### Beta File Scope + +- `beta_file_scope: object { id, type }` + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + +### Deleted File + +- `deleted_file: object { id, type }` + + - `id: string` + + ID of the deleted file. + + - `type: optional "file_deleted"` + + Deleted object type. + + For file deletion, this is always `"file_deleted"`. + + - `"file_deleted"` + +### File Metadata + +- `file_metadata: object { id, created_at, filename, 5 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: string` + + RFC 3339 datetime string representing when the file was created. + + - `filename: string` + + Original filename of the uploaded file. + + - `mime_type: string` + + MIME type of the file. + + - `size_bytes: number` + + Size of the file in bytes. + + - `type: "file"` + + Object type. + + For files, this is always `"file"`. + + - `downloadable: optional boolean` + + Whether the file can be downloaded. + + - `scope: optional object { id, type }` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + +# Skills + +## Create + +`$ ant beta:skills create` + +**post** `/v1/skills` + +Create Skill + +### Parameters + +- `--display-title: optional string` + + Body param: Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + +- `--file: optional array of string` + + Body param: Files to upload for the skill. + + All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillNewResponse: object { id, created_at, display_title, 4 more }` + + - `id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill was created. + + - `display_title: string` + + Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + + - `latest_version: string` + + The latest version identifier for the skill. + + This represents the most recent version of the skill that has been created. + + - `source: string` + + Source of the skill. + + This may be one of the following values: + + * `"custom"`: the skill was created by a user + * `"anthropic"`: the skill was created by Anthropic + + - `type: string` + + Object type. + + For Skills, this is always `"skill"`. + + - `updated_at: string` + + ISO 8601 timestamp of when the skill was last updated. + +### Example + +```cli +ant beta:skills create \ + --api-key my-anthropic-api-key +``` + +## List + +`$ ant beta:skills list` + +**get** `/v1/skills` + +List Skills + +### Parameters + +- `--limit: optional number` + + Query param: Number of results to return per page. + + Maximum value is 100. Defaults to 20. + +- `--page: optional string` + + Query param: Pagination token for fetching a specific page of results. + + Pass the value from a previous response's `next_page` field to get the next page of results. + +- `--source: optional string` + + Query param: Filter skills by source. + + If provided, only skills from the specified source will be returned: + + * `"custom"`: only return user-created skills + * `"anthropic"`: only return Anthropic-created skills + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListSkillsResponse: object { data, has_more, next_page }` + + - `data: array of object { id, created_at, display_title, 4 more }` + + List of skills. + + - `id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill was created. + + - `display_title: string` + + Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + + - `latest_version: string` + + The latest version identifier for the skill. + + This represents the most recent version of the skill that has been created. + + - `source: string` + + Source of the skill. + + This may be one of the following values: + + * `"custom"`: the skill was created by a user + * `"anthropic"`: the skill was created by Anthropic + + - `type: string` + + Object type. + + For Skills, this is always `"skill"`. + + - `updated_at: string` + + ISO 8601 timestamp of when the skill was last updated. + + - `has_more: boolean` + + Whether there are more results available. + + If `true`, there are additional results that can be fetched using the `next_page` token. + + - `next_page: string` + + Token for fetching the next page of results. + + If `null`, there are no more results available. Pass this value to the `page_token` parameter in the next request to get the next page. + +### Example + +```cli +ant beta:skills list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant beta:skills retrieve` + +**get** `/v1/skills/{skill_id}` + +Get Skill + +### Parameters + +- `--skill-id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillGetResponse: object { id, created_at, display_title, 4 more }` + + - `id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill was created. + + - `display_title: string` + + Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + + - `latest_version: string` + + The latest version identifier for the skill. + + This represents the most recent version of the skill that has been created. + + - `source: string` + + Source of the skill. + + This may be one of the following values: + + * `"custom"`: the skill was created by a user + * `"anthropic"`: the skill was created by Anthropic + + - `type: string` + + Object type. + + For Skills, this is always `"skill"`. + + - `updated_at: string` + + ISO 8601 timestamp of when the skill was last updated. + +### Example + +```cli +ant beta:skills retrieve \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` + +## Delete + +`$ ant beta:skills delete` + +**delete** `/v1/skills/{skill_id}` + +Delete Skill + +### Parameters + +- `--skill-id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillDeleteResponse: object { id, type }` + + - `id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + + - `type: string` + + Deleted object type. + + For Skills, this is always `"skill_deleted"`. + +### Example + +```cli +ant beta:skills delete \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` + +# Versions + +## Create + +`$ ant beta:skills:versions create` + +**post** `/v1/skills/{skill_id}/versions` + +Create Skill Version + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--file: optional array of string` + + Body param: Files to upload for the skill. + + All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillVersionNewResponse: object { id, created_at, description, 5 more }` + + - `id: string` + + Unique identifier for the skill version. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill version was created. + + - `description: string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `directory: string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `name: string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `skill_id: string` + + Identifier for the skill that this version belongs to. + + - `type: string` + + Object type. + + For Skill Versions, this is always `"skill_version"`. + + - `version: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +### Example + +```cli +ant beta:skills:versions create \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` + +## List + +`$ ant beta:skills:versions list` + +**get** `/v1/skills/{skill_id}/versions` + +List Skill Versions + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--page: optional string` + + Query param: Optionally set to the `next_page` token from the previous response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListSkillVersionsResponse: object { data, has_more, next_page }` + + - `data: array of object { id, created_at, description, 5 more }` + + List of skill versions. + + - `id: string` + + Unique identifier for the skill version. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill version was created. + + - `description: string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `directory: string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `name: string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `skill_id: string` + + Identifier for the skill that this version belongs to. + + - `type: string` + + Object type. + + For Skill Versions, this is always `"skill_version"`. + + - `version: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `next_page: string` + + Token to provide in as `page` in the subsequent request to retrieve the next page of data. + +### Example + +```cli +ant beta:skills:versions list \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` + +## Retrieve + +`$ ant beta:skills:versions retrieve` + +**get** `/v1/skills/{skill_id}/versions/{version}` + +Get Skill Version + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--version: string` + + Path param: Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillVersionGetResponse: object { id, created_at, description, 5 more }` + + - `id: string` + + Unique identifier for the skill version. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill version was created. + + - `description: string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `directory: string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `name: string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `skill_id: string` + + Identifier for the skill that this version belongs to. + + - `type: string` + + Object type. + + For Skill Versions, this is always `"skill_version"`. + + - `version: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +### Example + +```cli +ant beta:skills:versions retrieve \ + --api-key my-anthropic-api-key \ + --skill-id skill_id \ + --version version +``` + +## Delete + +`$ ant beta:skills:versions delete` + +**delete** `/v1/skills/{skill_id}/versions/{version}` + +Delete Skill Version + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--version: string` + + Path param: Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillVersionDeleteResponse: object { id, type }` + + - `id: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + + - `type: string` + + Deleted object type. + + For Skill Versions, this is always `"skill_version_deleted"`. + +### Example + +```cli +ant beta:skills:versions delete \ + --api-key my-anthropic-api-key \ + --skill-id skill_id \ + --version version +``` diff --git a/content/en/api/cli/beta/agents.md b/content/en/api/cli/beta/agents.md new file mode 100644 index 000000000..30d8fcb78 --- /dev/null +++ b/content/en/api/cli/beta/agents.md @@ -0,0 +1,3224 @@ +# Agents + +## Create + +`$ ant beta:agents create` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `--model: BetaManagedAgentsModelConfigParams` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + +- `--name: string` + + Body param: Human-readable name for the agent. 1-256 characters. + +- `--description: optional string` + + Body param: Description of what the agent does. Up to 2048 characters. + +- `--mcp-server: optional array of BetaManagedAgentsURLMCPServerParams` + + Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + +- `--skill: optional array of BetaManagedAgentsSkillParams` + + Body param: Skills available to the agent. Maximum 20. + +- `--system: optional string` + + Body param: System prompt for the agent. Up to 100,000 characters. + +- `--tool: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` + + Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```cli +ant beta:agents create \ + --api-key my-anthropic-api-key \ + --model '{id: claude-opus-4-6}' \ + --name 'My First Agent' +``` + +## List + +`$ ant beta:agents list` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `--created-at-gte: optional string` + + Query param: Return agents created at or after this time (inclusive). + +- `--created-at-lte: optional string` + + Query param: Return agents created at or before this time (inclusive). + +- `--include-archived: optional boolean` + + Query param: Include archived agents in results. Defaults to false. + +- `--limit: optional number` + + Query param: Maximum results per page. Default 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination cursor from a previous response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListAgents: object { data, next_page }` + + Paginated list of agents. + + - `data: optional array of BetaManagedAgentsAgent` + + List of agents. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:agents list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant beta:agents retrieve` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `--agent-id: string` + + Path param: Path parameter agent_id + +- `--version: optional number` + + Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```cli +ant beta:agents retrieve \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP +``` + +## Update + +`$ ant beta:agents update` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `--agent-id: string` + + Path param: Path parameter agent_id + +- `--version: number` + + Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + +- `--description: optional string` + + Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + +- `--mcp-server: optional array of BetaManagedAgentsURLMCPServerParams` + + Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + +- `--model: optional BetaManagedAgentsModelConfigParams` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + +- `--name: optional string` + + Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + +- `--skill: optional array of BetaManagedAgentsSkillParams` + + Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + +- `--system: optional string` + + Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + +- `--tool: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` + + Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```cli +ant beta:agents update \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP \ + --version 1 +``` + +## Archive + +`$ ant beta:agents archive` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `--agent-id: string` + + Path parameter agent_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```cli +ant beta:agents archive \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `beta_managed_agents_agent_tool_config: object { enabled, name, permission_policy }` + + Configuration for a specific agent tool. + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Tool Config Params + +- `beta_managed_agents_agent_tool_config_params: object { name, enabled, permission_policy }` + + Configuration override for a specific tool within a toolset. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config + +- `beta_managed_agents_agent_toolset_default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `beta_managed_agents_agent_toolset_default_config_params: object { enabled, permission_policy }` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset20260401 + +- `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `beta_managed_agents_agent_toolset20260401_params: object { type, configs, default_config }` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` + + Per-tool configuration overrides. + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: optional boolean` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional object { enabled, permission_policy }` + + Default configuration for all tools in a toolset. + + - `enabled: optional boolean` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Always Allow Policy + +- `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + +### Beta Managed Agents Always Ask Policy + +- `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Anthropic Skill + +- `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + +### Beta Managed Agents Anthropic Skill Params + +- `beta_managed_agents_anthropic_skill_params: object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + +### Beta Managed Agents Custom Skill Params + +- `beta_managed_agents_custom_skill_params: object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + +### Beta Managed Agents Custom Tool Input Schema + +- `beta_managed_agents_custom_tool_input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + +### Beta Managed Agents Custom Tool Params + +- `beta_managed_agents_custom_tool_params: object { description, input_schema, name, type }` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + +### Beta Managed Agents MCP Server URL Definition + +- `beta_managed_agents_mcp_server_url_definition: object { name, type, url }` + + URL-based MCP server connection as returned in API responses. + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + +### Beta Managed Agents MCP Tool Config + +- `beta_managed_agents_mcp_tool_config: object { enabled, name, permission_policy }` + + Resolved configuration for a specific MCP tool. + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Tool Config Params + +- `beta_managed_agents_mcp_tool_config_params: object { name, enabled, permission_policy }` + + Configuration override for a specific MCP tool. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset + +- `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + +### Beta Managed Agents MCP Toolset Default Config + +- `beta_managed_agents_mcp_toolset_default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `beta_managed_agents_mcp_toolset_default_config_params: object { enabled, permission_policy }` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Params + +- `beta_managed_agents_mcp_toolset_params: object { mcp_server_name, type, configs, default_config }` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: optional boolean` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: optional object { enabled, permission_policy }` + + Default configuration for all tools from an MCP server. + + - `enabled: optional boolean` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Model Config + +- `beta_managed_agents_model_config: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Model Config Params + +- `beta_managed_agents_model_config_params: object { id, speed }` + + An object that defines additional configuration control over model use + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Skill Params + +- `beta_managed_agents_skill_params: BetaManagedAgentsAnthropicSkillParams or BetaManagedAgentsCustomSkillParams` + + Skill to load in the session container. + + - `beta_managed_agents_anthropic_skill_params: object { skill_id, type, version }` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + + - `beta_managed_agents_custom_skill_params: object { skill_id, type, version }` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version: optional string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `beta_managed_agents_url_mcp_server_params: object { name, type, url }` + + URL-based MCP server connection. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + +# Versions + +## List + +`$ ant beta:agents:versions list` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `--agent-id: string` + + Path param: Path parameter agent_id + +- `--limit: optional number` + + Query param: Maximum results per page. Default 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination cursor. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListAgentVersions: object { data, next_page }` + + Paginated list of agent versions. + + - `data: optional array of BetaManagedAgentsAgent` + + Agent versions. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:agents:versions list \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP +``` diff --git a/content/en/api/cli/beta/agents/archive.md b/content/en/api/cli/beta/agents/archive.md new file mode 100644 index 000000000..2deff6b6e --- /dev/null +++ b/content/en/api/cli/beta/agents/archive.md @@ -0,0 +1,315 @@ +## Archive + +`$ ant beta:agents archive` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `--agent-id: string` + + Path parameter agent_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```cli +ant beta:agents archive \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP +``` diff --git a/content/en/api/cli/beta/agents/create.md b/content/en/api/cli/beta/agents/create.md new file mode 100644 index 000000000..8a31871e6 --- /dev/null +++ b/content/en/api/cli/beta/agents/create.md @@ -0,0 +1,344 @@ +## Create + +`$ ant beta:agents create` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `--model: BetaManagedAgentsModelConfigParams` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + +- `--name: string` + + Body param: Human-readable name for the agent. 1-256 characters. + +- `--description: optional string` + + Body param: Description of what the agent does. Up to 2048 characters. + +- `--mcp-server: optional array of BetaManagedAgentsURLMCPServerParams` + + Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + +- `--skill: optional array of BetaManagedAgentsSkillParams` + + Body param: Skills available to the agent. Maximum 20. + +- `--system: optional string` + + Body param: System prompt for the agent. Up to 100,000 characters. + +- `--tool: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` + + Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```cli +ant beta:agents create \ + --api-key my-anthropic-api-key \ + --model '{id: claude-opus-4-6}' \ + --name 'My First Agent' +``` diff --git a/content/en/api/cli/beta/agents/list.md b/content/en/api/cli/beta/agents/list.md new file mode 100644 index 000000000..aa29354b2 --- /dev/null +++ b/content/en/api/cli/beta/agents/list.md @@ -0,0 +1,338 @@ +## List + +`$ ant beta:agents list` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `--created-at-gte: optional string` + + Query param: Return agents created at or after this time (inclusive). + +- `--created-at-lte: optional string` + + Query param: Return agents created at or before this time (inclusive). + +- `--include-archived: optional boolean` + + Query param: Include archived agents in results. Defaults to false. + +- `--limit: optional number` + + Query param: Maximum results per page. Default 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination cursor from a previous response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListAgents: object { data, next_page }` + + Paginated list of agents. + + - `data: optional array of BetaManagedAgentsAgent` + + List of agents. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:agents list \ + --api-key my-anthropic-api-key +``` diff --git a/content/en/api/cli/beta/agents/retrieve.md b/content/en/api/cli/beta/agents/retrieve.md new file mode 100644 index 000000000..5a4fd15e2 --- /dev/null +++ b/content/en/api/cli/beta/agents/retrieve.md @@ -0,0 +1,319 @@ +## Retrieve + +`$ ant beta:agents retrieve` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `--agent-id: string` + + Path param: Path parameter agent_id + +- `--version: optional number` + + Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```cli +ant beta:agents retrieve \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP +``` diff --git a/content/en/api/cli/beta/agents/update.md b/content/en/api/cli/beta/agents/update.md new file mode 100644 index 000000000..4028251d0 --- /dev/null +++ b/content/en/api/cli/beta/agents/update.md @@ -0,0 +1,352 @@ +## Update + +`$ ant beta:agents update` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `--agent-id: string` + + Path param: Path parameter agent_id + +- `--version: number` + + Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + +- `--description: optional string` + + Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + +- `--mcp-server: optional array of BetaManagedAgentsURLMCPServerParams` + + Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + +- `--model: optional BetaManagedAgentsModelConfigParams` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + +- `--name: optional string` + + Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + +- `--skill: optional array of BetaManagedAgentsSkillParams` + + Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + +- `--system: optional string` + + Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + +- `--tool: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` + + Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_agent: object { id, archived_at, created_at, 11 more }` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```cli +ant beta:agents update \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP \ + --version 1 +``` diff --git a/content/en/api/cli/beta/agents/versions.md b/content/en/api/cli/beta/agents/versions.md new file mode 100644 index 000000000..78f70fea6 --- /dev/null +++ b/content/en/api/cli/beta/agents/versions.md @@ -0,0 +1,333 @@ +# Versions + +## List + +`$ ant beta:agents:versions list` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `--agent-id: string` + + Path param: Path parameter agent_id + +- `--limit: optional number` + + Query param: Maximum results per page. Default 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination cursor. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListAgentVersions: object { data, next_page }` + + Paginated list of agent versions. + + - `data: optional array of BetaManagedAgentsAgent` + + Agent versions. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:agents:versions list \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP +``` diff --git a/content/en/api/cli/beta/agents/versions/list.md b/content/en/api/cli/beta/agents/versions/list.md new file mode 100644 index 000000000..a69689a21 --- /dev/null +++ b/content/en/api/cli/beta/agents/versions/list.md @@ -0,0 +1,331 @@ +## List + +`$ ant beta:agents:versions list` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `--agent-id: string` + + Path param: Path parameter agent_id + +- `--limit: optional number` + + Query param: Maximum results per page. Default 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination cursor. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListAgentVersions: object { data, next_page }` + + Paginated list of agent versions. + + - `data: optional array of BetaManagedAgentsAgent` + + Agent versions. + + - `id: string` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: map[string]` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:agents:versions list \ + --api-key my-anthropic-api-key \ + --agent-id agent_011CZkYpogX7uDKUyvBTophP +``` diff --git a/content/en/api/cli/beta/environments.md b/content/en/api/cli/beta/environments.md new file mode 100644 index 000000000..12a6a548d --- /dev/null +++ b/content/en/api/cli/beta/environments.md @@ -0,0 +1,1196 @@ +# Environments + +## Create + +`$ ant beta:environments create` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `--name: string` + + Body param: Human-readable name for the environment + +- `--config: optional object { type, networking, packages }` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + +- `--description: optional string` + + Body param: Optional description of the environment + +- `--metadata: optional map[string]` + + Body param: User-provided metadata key-value pairs + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```cli +ant beta:environments create \ + --api-key my-anthropic-api-key \ + --name python-data-analysis +``` + +## List + +`$ ant beta:environments list` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `--include-archived: optional boolean` + + Query param: Include archived environments in the response + +- `--limit: optional number` + + Query param: Maximum number of environments to return + +- `--page: optional string` + + Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaEnvironmentListResponse: object { data, next_page }` + + Response when listing environments. + + This response model uses opaque cursor-based pagination. Use the `page` + query parameter with the value from `next_page` to fetch the next page. + + - `data: array of BetaEnvironment` + + List of environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + + - `next_page: string` + + Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request. + +### Example + +```cli +ant beta:environments list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant beta:environments retrieve` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `--environment-id: string` + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```cli +ant beta:environments retrieve \ + --api-key my-anthropic-api-key \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` + +## Update + +`$ ant beta:environments update` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `--environment-id: string` + + Path param + +- `--config: optional object { type, networking, packages }` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + +- `--description: optional string` + + Body param: Updated description of the environment + +- `--metadata: optional map[string]` + + Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + +- `--name: optional string` + + Body param: Updated name for the environment + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```cli +ant beta:environments update \ + --api-key my-anthropic-api-key \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` + +## Delete + +`$ ant beta:environments delete` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `--environment-id: string` + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment_delete_response: object { id, type }` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + +### Example + +```cli +ant beta:environments delete \ + --api-key my-anthropic-api-key \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` + +## Archive + +`$ ant beta:environments archive` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `--environment-id: string` + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```cli +ant beta:environments archive \ + --api-key my-anthropic-api-key \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` + +## Domain Types + +### Beta Cloud Config + +- `beta_cloud_config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + +### Beta Cloud Config Params + +- `beta_cloud_config_params: object { type, networking, packages }` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network_params: object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + + - `packages: optional object { apt, cargo, gem, 4 more }` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +### Beta Environment + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `beta_environment_delete_response: object { id, type }` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + +### Beta Limited Network + +- `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + +### Beta Limited Network Params + +- `beta_limited_network_params: object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `allow_mcp_servers: optional boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: optional boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: optional array of string` + + Specifies domains the container can reach. + +### Beta Packages + +- `beta_packages: object { apt, cargo, gem, 4 more }` + + Packages (and their versions) available in this environment. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +### Beta Packages Params + +- `beta_packages_params: object { apt, cargo, gem, 4 more }` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: optional array of string` + + Ubuntu/Debian packages to install + + - `cargo: optional array of string` + + Rust packages to install + + - `gem: optional array of string` + + Ruby packages to install + + - `go: optional array of string` + + Go packages to install + + - `npm: optional array of string` + + Node.js packages to install + + - `pip: optional array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + +### Beta Unrestricted Network + +- `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type diff --git a/content/en/api/cli/beta/environments/archive.md b/content/en/api/cli/beta/environments/archive.md new file mode 100644 index 000000000..b5302e1eb --- /dev/null +++ b/content/en/api/cli/beta/environments/archive.md @@ -0,0 +1,135 @@ +## Archive + +`$ ant beta:environments archive` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `--environment-id: string` + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```cli +ant beta:environments archive \ + --api-key my-anthropic-api-key \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` diff --git a/content/en/api/cli/beta/environments/create.md b/content/en/api/cli/beta/environments/create.md new file mode 100644 index 000000000..63f39842d --- /dev/null +++ b/content/en/api/cli/beta/environments/create.md @@ -0,0 +1,152 @@ +## Create + +`$ ant beta:environments create` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `--name: string` + + Body param: Human-readable name for the environment + +- `--config: optional object { type, networking, packages }` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + +- `--description: optional string` + + Body param: Optional description of the environment + +- `--metadata: optional map[string]` + + Body param: User-provided metadata key-value pairs + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```cli +ant beta:environments create \ + --api-key my-anthropic-api-key \ + --name python-data-analysis +``` diff --git a/content/en/api/cli/beta/environments/delete.md b/content/en/api/cli/beta/environments/delete.md new file mode 100644 index 000000000..52ef19e2c --- /dev/null +++ b/content/en/api/cli/beta/environments/delete.md @@ -0,0 +1,37 @@ +## Delete + +`$ ant beta:environments delete` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `--environment-id: string` + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment_delete_response: object { id, type }` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + +### Example + +```cli +ant beta:environments delete \ + --api-key my-anthropic-api-key \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` diff --git a/content/en/api/cli/beta/environments/list.md b/content/en/api/cli/beta/environments/list.md new file mode 100644 index 000000000..a880e66a9 --- /dev/null +++ b/content/en/api/cli/beta/environments/list.md @@ -0,0 +1,155 @@ +## List + +`$ ant beta:environments list` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `--include-archived: optional boolean` + + Query param: Include archived environments in the response + +- `--limit: optional number` + + Query param: Maximum number of environments to return + +- `--page: optional string` + + Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaEnvironmentListResponse: object { data, next_page }` + + Response when listing environments. + + This response model uses opaque cursor-based pagination. Use the `page` + query parameter with the value from `next_page` to fetch the next page. + + - `data: array of BetaEnvironment` + + List of environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + + - `next_page: string` + + Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request. + +### Example + +```cli +ant beta:environments list \ + --api-key my-anthropic-api-key +``` diff --git a/content/en/api/cli/beta/environments/retrieve.md b/content/en/api/cli/beta/environments/retrieve.md new file mode 100644 index 000000000..785eba30c --- /dev/null +++ b/content/en/api/cli/beta/environments/retrieve.md @@ -0,0 +1,135 @@ +## Retrieve + +`$ ant beta:environments retrieve` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `--environment-id: string` + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```cli +ant beta:environments retrieve \ + --api-key my-anthropic-api-key \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` diff --git a/content/en/api/cli/beta/environments/update.md b/content/en/api/cli/beta/environments/update.md new file mode 100644 index 000000000..e131fbe97 --- /dev/null +++ b/content/en/api/cli/beta/environments/update.md @@ -0,0 +1,156 @@ +## Update + +`$ ant beta:environments update` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `--environment-id: string` + + Path param + +- `--config: optional object { type, networking, packages }` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + +- `--description: optional string` + + Body param: Updated description of the environment + +- `--metadata: optional map[string]` + + Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + +- `--name: optional string` + + Body param: Updated name for the environment + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_environment: object { id, archived_at, config, 6 more }` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: object { networking, packages, type }` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` + + Network configuration policy. + + - `beta_unrestricted_network: object { type }` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `beta_limited_network: object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: array of string` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `packages: object { apt, cargo, gem, 4 more }` + + Package manager configuration. + + - `apt: array of string` + + Ubuntu/Debian packages to install + + - `cargo: array of string` + + Rust packages to install + + - `gem: array of string` + + Ruby packages to install + + - `go: array of string` + + Go packages to install + + - `npm: array of string` + + Node.js packages to install + + - `pip: array of string` + + Python packages to install + + - `type: optional "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: map[string]` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```cli +ant beta:environments update \ + --api-key my-anthropic-api-key \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` diff --git a/content/en/api/cli/beta/files.md b/content/en/api/cli/beta/files.md index c816c74e5..1d6bcfda2 100644 --- a/content/en/api/cli/beta/files.md +++ b/content/en/api/cli/beta/files.md @@ -1 +1,402 @@ -Not Found - Claude API Docs
      \ No newline at end of file +# Files + +## Upload + +`$ ant beta:files upload` + +**post** `/v1/files` + +Upload File + +### Parameters + +- `--file: string` + + Body param: The file to upload + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `file_metadata: object { id, created_at, filename, 5 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: string` + + RFC 3339 datetime string representing when the file was created. + + - `filename: string` + + Original filename of the uploaded file. + + - `mime_type: string` + + MIME type of the file. + + - `size_bytes: number` + + Size of the file in bytes. + + - `type: "file"` + + Object type. + + For files, this is always `"file"`. + + - `downloadable: optional boolean` + + Whether the file can be downloaded. + + - `scope: optional object { id, type }` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + +### Example + +```cli +ant beta:files upload \ + --api-key my-anthropic-api-key \ + --file 'Example data' +``` + +## List + +`$ ant beta:files list` + +**get** `/v1/files` + +List Files + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--scope-id: optional string` + + Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaFileListResponse: object { data, first_id, has_more, last_id }` + + - `data: array of FileMetadata` + + List of file metadata objects. + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: string` + + RFC 3339 datetime string representing when the file was created. + + - `filename: string` + + Original filename of the uploaded file. + + - `mime_type: string` + + MIME type of the file. + + - `size_bytes: number` + + Size of the file in bytes. + + - `type: "file"` + + Object type. + + For files, this is always `"file"`. + + - `downloadable: optional boolean` + + Whether the file can be downloaded. + + - `scope: optional object { id, type }` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `first_id: optional string` + + ID of the first file in this page of results. + + - `has_more: optional boolean` + + Whether there are more results available. + + - `last_id: optional string` + + ID of the last file in this page of results. + +### Example + +```cli +ant beta:files list \ + --api-key my-anthropic-api-key +``` + +## Download + +`$ ant beta:files download` + +**get** `/v1/files/{file_id}/content` + +Download File + +### Parameters + +- `--file-id: string` + + ID of the File. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `unnamed_schema_0: file path` + +### Example + +```cli +ant beta:files download \ + --api-key my-anthropic-api-key \ + --file-id file_id +``` + +## Retrieve Metadata + +`$ ant beta:files retrieve-metadata` + +**get** `/v1/files/{file_id}` + +Get File Metadata + +### Parameters + +- `--file-id: string` + + ID of the File. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `file_metadata: object { id, created_at, filename, 5 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: string` + + RFC 3339 datetime string representing when the file was created. + + - `filename: string` + + Original filename of the uploaded file. + + - `mime_type: string` + + MIME type of the file. + + - `size_bytes: number` + + Size of the file in bytes. + + - `type: "file"` + + Object type. + + For files, this is always `"file"`. + + - `downloadable: optional boolean` + + Whether the file can be downloaded. + + - `scope: optional object { id, type }` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + +### Example + +```cli +ant beta:files retrieve-metadata \ + --api-key my-anthropic-api-key \ + --file-id file_id +``` + +## Delete + +`$ ant beta:files delete` + +**delete** `/v1/files/{file_id}` + +Delete File + +### Parameters + +- `--file-id: string` + + ID of the File. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `deleted_file: object { id, type }` + + - `id: string` + + ID of the deleted file. + + - `type: optional "file_deleted"` + + Deleted object type. + + For file deletion, this is always `"file_deleted"`. + + - `"file_deleted"` + +### Example + +```cli +ant beta:files delete \ + --api-key my-anthropic-api-key \ + --file-id file_id +``` + +## Domain Types + +### Beta File Scope + +- `beta_file_scope: object { id, type }` + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + +### Deleted File + +- `deleted_file: object { id, type }` + + - `id: string` + + ID of the deleted file. + + - `type: optional "file_deleted"` + + Deleted object type. + + For file deletion, this is always `"file_deleted"`. + + - `"file_deleted"` + +### File Metadata + +- `file_metadata: object { id, created_at, filename, 5 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: string` + + RFC 3339 datetime string representing when the file was created. + + - `filename: string` + + Original filename of the uploaded file. + + - `mime_type: string` + + MIME type of the file. + + - `size_bytes: number` + + Size of the file in bytes. + + - `type: "file"` + + Object type. + + For files, this is always `"file"`. + + - `downloadable: optional boolean` + + Whether the file can be downloaded. + + - `scope: optional object { id, type }` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). diff --git a/content/en/api/cli/beta/files/delete.md b/content/en/api/cli/beta/files/delete.md index 5d7020f86..a102891af 100644 --- a/content/en/api/cli/beta/files/delete.md +++ b/content/en/api/cli/beta/files/delete.md @@ -1 +1,41 @@ -Not Found - Claude API Docs
        \ No newline at end of file +## Delete + +`$ ant beta:files delete` + +**delete** `/v1/files/{file_id}` + +Delete File + +### Parameters + +- `--file-id: string` + + ID of the File. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `deleted_file: object { id, type }` + + - `id: string` + + ID of the deleted file. + + - `type: optional "file_deleted"` + + Deleted object type. + + For file deletion, this is always `"file_deleted"`. + + - `"file_deleted"` + +### Example + +```cli +ant beta:files delete \ + --api-key my-anthropic-api-key \ + --file-id file_id +``` diff --git a/content/en/api/cli/beta/files/download.md b/content/en/api/cli/beta/files/download.md index f1012e8cb..2370f46ce 100644 --- a/content/en/api/cli/beta/files/download.md +++ b/content/en/api/cli/beta/files/download.md @@ -1 +1,29 @@ -Not Found - Claude API Docs
          \ No newline at end of file +## Download + +`$ ant beta:files download` + +**get** `/v1/files/{file_id}/content` + +Download File + +### Parameters + +- `--file-id: string` + + ID of the File. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `unnamed_schema_0: file path` + +### Example + +```cli +ant beta:files download \ + --api-key my-anthropic-api-key \ + --file-id file_id +``` diff --git a/content/en/api/cli/beta/files/list.md b/content/en/api/cli/beta/files/list.md index 38038a879..b2f3261e5 100644 --- a/content/en/api/cli/beta/files/list.md +++ b/content/en/api/cli/beta/files/list.md @@ -1 +1,102 @@ -Not Found - Claude API Docs
            \ No newline at end of file +## List + +`$ ant beta:files list` + +**get** `/v1/files` + +List Files + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--scope-id: optional string` + + Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaFileListResponse: object { data, first_id, has_more, last_id }` + + - `data: array of FileMetadata` + + List of file metadata objects. + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: string` + + RFC 3339 datetime string representing when the file was created. + + - `filename: string` + + Original filename of the uploaded file. + + - `mime_type: string` + + MIME type of the file. + + - `size_bytes: number` + + Size of the file in bytes. + + - `type: "file"` + + Object type. + + For files, this is always `"file"`. + + - `downloadable: optional boolean` + + Whether the file can be downloaded. + + - `scope: optional object { id, type }` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `first_id: optional string` + + ID of the first file in this page of results. + + - `has_more: optional boolean` + + Whether there are more results available. + + - `last_id: optional string` + + ID of the last file in this page of results. + +### Example + +```cli +ant beta:files list \ + --api-key my-anthropic-api-key +``` diff --git a/content/en/api/cli/beta/files/retrieve_metadata.md b/content/en/api/cli/beta/files/retrieve_metadata.md index 0dd556855..8bf47132b 100644 --- a/content/en/api/cli/beta/files/retrieve_metadata.md +++ b/content/en/api/cli/beta/files/retrieve_metadata.md @@ -1 +1,73 @@ -Not Found - Claude API Docs
              \ No newline at end of file +## Retrieve Metadata + +`$ ant beta:files retrieve-metadata` + +**get** `/v1/files/{file_id}` + +Get File Metadata + +### Parameters + +- `--file-id: string` + + ID of the File. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `file_metadata: object { id, created_at, filename, 5 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: string` + + RFC 3339 datetime string representing when the file was created. + + - `filename: string` + + Original filename of the uploaded file. + + - `mime_type: string` + + MIME type of the file. + + - `size_bytes: number` + + Size of the file in bytes. + + - `type: "file"` + + Object type. + + For files, this is always `"file"`. + + - `downloadable: optional boolean` + + Whether the file can be downloaded. + + - `scope: optional object { id, type }` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + +### Example + +```cli +ant beta:files retrieve-metadata \ + --api-key my-anthropic-api-key \ + --file-id file_id +``` diff --git a/content/en/api/cli/beta/files/upload.md b/content/en/api/cli/beta/files/upload.md index 85784587f..c31aae6e1 100644 --- a/content/en/api/cli/beta/files/upload.md +++ b/content/en/api/cli/beta/files/upload.md @@ -1 +1,73 @@ -Not Found - Claude API Docs
                \ No newline at end of file +## Upload + +`$ ant beta:files upload` + +**post** `/v1/files` + +Upload File + +### Parameters + +- `--file: string` + + Body param: The file to upload + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `file_metadata: object { id, created_at, filename, 5 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: string` + + RFC 3339 datetime string representing when the file was created. + + - `filename: string` + + Original filename of the uploaded file. + + - `mime_type: string` + + MIME type of the file. + + - `size_bytes: number` + + Size of the file in bytes. + + - `type: "file"` + + Object type. + + For files, this is always `"file"`. + + - `downloadable: optional boolean` + + Whether the file can be downloaded. + + - `scope: optional object { id, type }` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + +### Example + +```cli +ant beta:files upload \ + --api-key my-anthropic-api-key \ + --file 'Example data' +``` diff --git a/content/en/api/cli/beta/messages.md b/content/en/api/cli/beta/messages.md index 74089d159..670b94b34 100644 --- a/content/en/api/cli/beta/messages.md +++ b/content/en/api/cli/beta/messages.md @@ -1 +1,26439 @@ -Not Found - Claude API Docs
                  \ No newline at end of file +# Messages + +## Create + +`$ ant beta:messages create` + +**post** `/v1/messages` + +Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. + +The Messages API can be used for either single queries or stateless multi-turn conversations. + +Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup) + +### Parameters + +- `--max-tokens: number` + + Body param: The maximum number of tokens to generate before stopping. + + Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. + + Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. + +- `--message: array of BetaMessageParam` + + Body param: Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + +- `--model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + Body param: The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--cache-control: optional object { type, ttl }` + + Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--container: optional BetaContainerParams or string` + + Body param: Container identifier for reuse across requests. + +- `--context-management: optional object { edits }` + + Body param: Context management configuration. + + This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. + +- `--inference-geo: optional string` + + Body param: Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. + +- `--mcp-server: optional array of BetaRequestMCPServerURLDefinition` + + Body param: MCP servers to be utilized in this request + +- `--metadata: optional object { user_id }` + + Body param: An object describing metadata about the request. + +- `--output-config: optional object { effort, format }` + + Body param: Configuration options for the model's output, such as the output format. + +- `--output-format: optional object { schema, type }` + + Body param: Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + A schema to specify Claude's output format in responses. This parameter will be removed in a future release. + +- `--service-tier: optional "auto" or "standard_only"` + + Body param: Determines whether to use priority capacity (if available) or standard capacity for this request. + + Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. + +- `--speed: optional "standard" or "fast"` + + Body param: The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. + +- `--stop-sequence: optional array of string` + + Body param: Custom text sequences that will cause the model to stop generating. + + Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. + + If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. + +- `--system: optional string or array of BetaTextBlockParam` + + Body param: System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + +- `--temperature: optional number` + + Body param: Amount of randomness injected into the response. + + Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. + + Note that even with `temperature` of `0.0`, the results will not be fully deterministic. + +- `--thinking: optional BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigAdaptive` + + Body param: Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + +- `--tool-choice: optional BetaToolChoiceAuto or BetaToolChoiceAny or BetaToolChoiceTool or BetaToolChoiceNone` + + Body param: How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + +- `--tool: optional array of BetaToolUnion` + + Body param: Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + +- `--top-k: optional number` + + Body param: Only sample from the top K options for each subsequent token. + + Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--top-p: optional number` + + Body param: Use nucleus sampling. + + In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + +### Example + +```cli +ant beta:messages create \ + --api-key my-anthropic-api-key \ + --max-tokens 1024 \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-opus-4-6 +``` + +## Count Tokens + +`$ ant beta:messages count-tokens` + +**post** `/v1/messages/count_tokens` + +Count the number of tokens in a Message. + +The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it. + +Learn more about token counting in our [user guide](https://docs.claude.com/en/docs/build-with-claude/token-counting) + +### Parameters + +- `--message: array of BetaMessageParam` + + Body param: Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + +- `--model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + Body param: The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--cache-control: optional object { type, ttl }` + + Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--context-management: optional object { edits }` + + Body param: Context management configuration. + + This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. + +- `--mcp-server: optional array of BetaRequestMCPServerURLDefinition` + + Body param: MCP servers to be utilized in this request + +- `--output-config: optional object { effort, format }` + + Body param: Configuration options for the model's output, such as the output format. + +- `--output-format: optional object { schema, type }` + + Body param: Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + A schema to specify Claude's output format in responses. This parameter will be removed in a future release. + +- `--speed: optional "standard" or "fast"` + + Body param: The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. + +- `--system: optional string or array of BetaTextBlockParam` + + Body param: System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + +- `--thinking: optional BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigAdaptive` + + Body param: Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + +- `--tool-choice: optional BetaToolChoiceAuto or BetaToolChoiceAny or BetaToolChoiceTool or BetaToolChoiceNone` + + Body param: How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + +- `--tool: optional array of BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 19 more` + + Body param: Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_tokens_count: object { context_management, input_tokens }` + + - `context_management: object { original_input_tokens }` + + Information about context management applied to the message. + + - `original_input_tokens: number` + + The original token count before context management was applied + + - `input_tokens: number` + + The total number of tokens across the provided list of messages, system prompt, and tools. + +### Example + +```cli +ant beta:messages count-tokens \ + --api-key my-anthropic-api-key \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-mythos-preview +``` + +## Domain Types + +### Beta All Thinking Turns + +- `beta_all_thinking_turns: object { type }` + + - `type: "all"` + +### Beta Base64 Image Source + +- `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + +### Beta Base64 PDF Source + +- `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + +### Beta Bash Code Execution Output Block + +- `beta_bash_code_execution_output_block: object { file_id, type }` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + +### Beta Bash Code Execution Output Block Param + +- `beta_bash_code_execution_output_block_param: object { file_id, type }` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + +### Beta Bash Code Execution Result Block + +- `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + +### Beta Bash Code Execution Result Block Param + +- `beta_bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + +### Beta Bash Code Execution Tool Result Block + +- `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + +### Beta Bash Code Execution Tool Result Block Param + +- `beta_bash_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam` + + - `beta_bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Bash Code Execution Tool Result Error + +- `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + +### Beta Bash Code Execution Tool Result Error Param + +- `beta_bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + +### Beta Cache Control Ephemeral + +- `beta_cache_control_ephemeral: object { type, ttl }` + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Cache Creation + +- `beta_cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + +### Beta Citation Char Location + +- `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + +### Beta Citation Char Location Param + +- `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + +### Beta Citation Config + +- `beta_citation_config: object { enabled }` + + - `enabled: boolean` + +### Beta Citation Content Block Location + +- `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + +### Beta Citation Content Block Location Param + +- `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + +### Beta Citation Page Location + +- `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + +### Beta Citation Page Location Param + +- `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + +### Beta Citation Search Result Location + +- `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Beta Citation Search Result Location Param + +- `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Beta Citation Web Search Result Location Param + +- `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + +### Beta Citations Config Param + +- `beta_citations_config_param: object { enabled }` + + - `enabled: optional boolean` + +### Beta Citations Delta + +- `beta_citations_delta: object { citation, type }` + + - `citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more` + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + +### Beta Citations Web Search Result Location + +- `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + +### Beta Clear Thinking 20251015 Edit + +- `beta_clear_thinking_20251015_edit: object { type, keep }` + + - `type: "clear_thinking_20251015"` + + - `keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"` + + Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. + + - `beta_thinking_turns: object { type, value }` + + - `type: "thinking_turns"` + + - `value: number` + + - `beta_all_thinking_turns: object { type }` + + - `type: "all"` + + - `union_member_2: "all"` + +### Beta Clear Thinking 20251015 Edit Response + +- `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + +### Beta Clear Tool Uses 20250919 Edit + +- `beta_clear_tool_uses_20250919_edit: object { type, clear_at_least, clear_tool_inputs, 3 more }` + + - `type: "clear_tool_uses_20250919"` + + - `clear_at_least: optional object { type, value }` + + Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed. + + - `type: "input_tokens"` + + - `value: number` + + - `clear_tool_inputs: optional boolean or array of string` + + Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) + + - `union_member_0: boolean` + + - `union_member_1: array of string` + + - `exclude_tools: optional array of string` + + Tool names whose uses are preserved from clearing + + - `keep: optional object { type, value }` + + Number of tool uses to retain in the conversation + + - `type: "tool_uses"` + + - `value: number` + + - `trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger` + + Condition that triggers the context management strategy + + - `beta_input_tokens_trigger: object { type, value }` + + - `type: "input_tokens"` + + - `value: number` + + - `beta_tool_uses_trigger: object { type, value }` + + - `type: "tool_uses"` + + - `value: number` + +### Beta Clear Tool Uses 20250919 Edit Response + +- `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + +### Beta Code Execution Output Block + +- `beta_code_execution_output_block: object { file_id, type }` + + - `file_id: string` + + - `type: "code_execution_output"` + +### Beta Code Execution Output Block Param + +- `beta_code_execution_output_block_param: object { file_id, type }` + + - `file_id: string` + + - `type: "code_execution_output"` + +### Beta Code Execution Result Block + +- `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + +### Beta Code Execution Result Block Param + +- `beta_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + +### Beta Code Execution Tool 20250522 + +- `beta_code_execution_tool_20250522: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250522"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Code Execution Tool 20250825 + +- `beta_code_execution_tool_20250825: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250825"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Code Execution Tool 20260120 + +- `beta_code_execution_tool_20260120: object { name, type, allowed_callers, 3 more }` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20260120"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Code Execution Tool Result Block + +- `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + +### Beta Code Execution Tool Result Block Content + +- `beta_code_execution_tool_result_block_content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Beta Code Execution Tool Result Block Param + +- `beta_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaCodeExecutionToolResultErrorParam or BetaCodeExecutionResultBlockParam or BetaEncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Code Execution Tool Result Block Param Content + +- `beta_code_execution_tool_result_block_param_content: BetaCodeExecutionToolResultErrorParam or BetaCodeExecutionResultBlockParam or BetaEncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Beta Code Execution Tool Result Error + +- `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + +### Beta Code Execution Tool Result Error Code + +- `beta_code_execution_tool_result_error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + +### Beta Code Execution Tool Result Error Param + +- `beta_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + +### Beta Compact 20260112 Edit + +- `beta_compact_20260112_edit: object { type, instructions, pause_after_compaction, trigger }` + + Automatically compact older context when reaching the configured trigger threshold. + + - `type: "compact_20260112"` + + - `instructions: optional string` + + Additional instructions for summarization. + + - `pause_after_compaction: optional boolean` + + Whether to pause after compaction and return the compaction block to the user. + + - `trigger: optional object { type, value }` + + When to trigger compaction. Defaults to 150000 input tokens. + + - `type: "input_tokens"` + + - `value: number` + +### Beta Compaction Block + +- `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + +### Beta Compaction Block Param + +- `beta_compaction_block_param: object { content, type, cache_control }` + + A compaction block containing summary of previous context. + + Users should round-trip these blocks from responses to subsequent requests + to maintain context across compaction boundaries. + + When content is None, the block represents a failed compaction. The server + treats these as no-ops. Empty string content is not allowed. + + - `content: string` + + Summary of previously compacted content, or null if compaction failed + + - `type: "compaction"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Compaction Content Block Delta + +- `beta_compaction_content_block_delta: object { content, type }` + + - `content: string` + + - `type: "compaction_delta"` + +### Beta Compaction Iteration Usage + +- `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + +### Beta Container + +- `beta_container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + +### Beta Container Params + +- `beta_container_params: object { id, skills }` + + Container parameters with skills to be loaded. + + - `id: optional string` + + Container id + + - `skills: optional array of BetaSkillParams` + + List of skills to load in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: optional string` + + Skill version or 'latest' for most recent version + +### Beta Container Upload Block + +- `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + +### Beta Container Upload Block Param + +- `beta_container_upload_block_param: object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Content Block + +- `beta_content_block: BetaTextBlock or BetaThinkingBlock or BetaRedactedThinkingBlock or 12 more` + + Response model for a file uploaded to the container. + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + +### Beta Content Block Param + +- `beta_content_block_param: BetaTextBlockParam or BetaImageBlockParam or BetaRequestDocumentBlock or 16 more` + + Regular text content. + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_request_document_block: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `beta_search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `beta_thinking_block_param: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block_param: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `beta_request_document_block: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `beta_tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + + - `beta_server_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: array of BetaWebSearchResultBlockParam or BetaWebSearchToolRequestError` + + - `Result Block: array of BetaWebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `beta_web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam` + + - `beta_web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaCodeExecutionToolResultErrorParam or BetaCodeExecutionResultBlockParam or BetaEncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_bash_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam` + + - `beta_bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_text_editor_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam` + + - `beta_text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `beta_text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `beta_text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_tool_search_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam` + + - `beta_tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_mcp_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_request_mcp_tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional string or array of BetaTextBlockParam` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_param_content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `is_error: optional boolean` + + - `beta_container_upload_block_param: object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_compaction_block_param: object { content, type, cache_control }` + + A compaction block containing summary of previous context. + + Users should round-trip these blocks from responses to subsequent requests + to maintain context across compaction boundaries. + + When content is None, the block represents a failed compaction. The server + treats these as no-ops. Empty string content is not allowed. + + - `content: string` + + Summary of previously compacted content, or null if compaction failed + + - `type: "compaction"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Content Block Source + +- `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + +### Beta Content Block Source Content + +- `beta_content_block_source_content: BetaTextBlockParam or BetaImageBlockParam` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Context Management Config + +- `beta_context_management_config: object { edits }` + + - `edits: optional array of BetaClearToolUses20250919Edit or BetaClearThinking20251015Edit or BetaCompact20260112Edit` + + List of context management edits to apply + + - `beta_clear_tool_uses_20250919_edit: object { type, clear_at_least, clear_tool_inputs, 3 more }` + + - `type: "clear_tool_uses_20250919"` + + - `clear_at_least: optional object { type, value }` + + Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed. + + - `type: "input_tokens"` + + - `value: number` + + - `clear_tool_inputs: optional boolean or array of string` + + Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) + + - `union_member_0: boolean` + + - `union_member_1: array of string` + + - `exclude_tools: optional array of string` + + Tool names whose uses are preserved from clearing + + - `keep: optional object { type, value }` + + Number of tool uses to retain in the conversation + + - `type: "tool_uses"` + + - `value: number` + + - `trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger` + + Condition that triggers the context management strategy + + - `beta_input_tokens_trigger: object { type, value }` + + - `type: "input_tokens"` + + - `value: number` + + - `beta_tool_uses_trigger: object { type, value }` + + - `type: "tool_uses"` + + - `value: number` + + - `beta_clear_thinking_20251015_edit: object { type, keep }` + + - `type: "clear_thinking_20251015"` + + - `keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"` + + Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. + + - `beta_thinking_turns: object { type, value }` + + - `type: "thinking_turns"` + + - `value: number` + + - `beta_all_thinking_turns: object { type }` + + - `type: "all"` + + - `union_member_2: "all"` + + - `beta_compact_20260112_edit: object { type, instructions, pause_after_compaction, trigger }` + + Automatically compact older context when reaching the configured trigger threshold. + + - `type: "compact_20260112"` + + - `instructions: optional string` + + Additional instructions for summarization. + + - `pause_after_compaction: optional boolean` + + Whether to pause after compaction and return the compaction block to the user. + + - `trigger: optional object { type, value }` + + When to trigger compaction. Defaults to 150000 input tokens. + + - `type: "input_tokens"` + + - `value: number` + +### Beta Context Management Response + +- `beta_context_management_response: object { applied_edits }` + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + +### Beta Count Tokens Context Management Response + +- `beta_count_tokens_context_management_response: object { original_input_tokens }` + + - `original_input_tokens: number` + + The original token count before context management was applied + +### Beta Direct Caller + +- `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + +### Beta Document Block + +- `beta_document_block: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + +### Beta Encrypted Code Execution Result Block + +- `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Beta Encrypted Code Execution Result Block Param + +- `beta_encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Beta File Document Source + +- `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + +### Beta File Image Source + +- `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + +### Beta Image Block Param + +- `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Input JSON Delta + +- `beta_input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + +### Beta Input Tokens Clear At Least + +- `beta_input_tokens_clear_at_least: object { type, value }` + + - `type: "input_tokens"` + + - `value: number` + +### Beta Input Tokens Trigger + +- `beta_input_tokens_trigger: object { type, value }` + + - `type: "input_tokens"` + + - `value: number` + +### Beta Iterations Usage + +- `beta_iterations_usage: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + +### Beta JSON Output Format + +- `beta_json_output_format: object { schema, type }` + + - `schema: map[unknown]` + + The JSON schema of the format + + - `type: "json_schema"` + +### Beta MCP Tool Config + +- `beta_mcp_tool_config: object { defer_loading, enabled }` + + Configuration for a specific tool in an MCP toolset. + + - `defer_loading: optional boolean` + + - `enabled: optional boolean` + +### Beta MCP Tool Default Config + +- `beta_mcp_tool_default_config: object { defer_loading, enabled }` + + Default configuration for tools in an MCP toolset. + + - `defer_loading: optional boolean` + + - `enabled: optional boolean` + +### Beta MCP Tool Result Block + +- `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + +### Beta MCP Tool Use Block + +- `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + +### Beta MCP Tool Use Block Param + +- `beta_mcp_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta MCP Toolset + +- `beta_mcp_toolset: object { mcp_server_name, type, cache_control, 2 more }` + + Configuration for a group of tools from an MCP server. + + Allows configuring enabled status and defer_loading for all tools + from an MCP server, with optional per-tool overrides. + + - `mcp_server_name: string` + + Name of the MCP server to configure tools for + + - `type: "mcp_toolset"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `configs: optional map[BetaMCPToolConfig]` + + Configuration overrides for specific tools, keyed by tool name + + - `defer_loading: optional boolean` + + - `enabled: optional boolean` + + - `default_config: optional object { defer_loading, enabled }` + + Default configuration applied to all tools from this server + + - `defer_loading: optional boolean` + + - `enabled: optional boolean` + +### Beta Memory Tool 20250818 + +- `beta_memory_tool_20250818: object { name, type, allowed_callers, 4 more }` + + - `name: "memory"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "memory_20250818"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Memory Tool 20250818 Command + +- `beta_memory_tool_20250818_command: BetaMemoryTool20250818ViewCommand or BetaMemoryTool20250818CreateCommand or BetaMemoryTool20250818StrReplaceCommand or 3 more` + + - `beta_memory_tool_20250818_view_command: object { command, path, view_range }` + + - `command: "view"` + + Command type identifier + + - `path: string` + + Path to directory or file to view + + - `view_range: optional array of number` + + Optional line range for viewing specific lines + + - `beta_memory_tool_20250818_create_command: object { command, file_text, path }` + + - `command: "create"` + + Command type identifier + + - `file_text: string` + + Content to write to the file + + - `path: string` + + Path where the file should be created + + - `beta_memory_tool_20250818_str_replace_command: object { command, new_str, old_str, path }` + + - `command: "str_replace"` + + Command type identifier + + - `new_str: string` + + Text to replace with + + - `old_str: string` + + Text to search for and replace + + - `path: string` + + Path to the file where text should be replaced + + - `beta_memory_tool_20250818_insert_command: object { command, insert_line, insert_text, path }` + + - `command: "insert"` + + Command type identifier + + - `insert_line: number` + + Line number where text should be inserted + + - `insert_text: string` + + Text to insert at the specified line + + - `path: string` + + Path to the file where text should be inserted + + - `beta_memory_tool_20250818_delete_command: object { command, path }` + + - `command: "delete"` + + Command type identifier + + - `path: string` + + Path to the file or directory to delete + + - `beta_memory_tool_20250818_rename_command: object { command, new_path, old_path }` + + - `command: "rename"` + + Command type identifier + + - `new_path: string` + + New path for the file or directory + + - `old_path: string` + + Current path of the file or directory + +### Beta Memory Tool 20250818 Create Command + +- `beta_memory_tool_20250818_create_command: object { command, file_text, path }` + + - `command: "create"` + + Command type identifier + + - `file_text: string` + + Content to write to the file + + - `path: string` + + Path where the file should be created + +### Beta Memory Tool 20250818 Delete Command + +- `beta_memory_tool_20250818_delete_command: object { command, path }` + + - `command: "delete"` + + Command type identifier + + - `path: string` + + Path to the file or directory to delete + +### Beta Memory Tool 20250818 Insert Command + +- `beta_memory_tool_20250818_insert_command: object { command, insert_line, insert_text, path }` + + - `command: "insert"` + + Command type identifier + + - `insert_line: number` + + Line number where text should be inserted + + - `insert_text: string` + + Text to insert at the specified line + + - `path: string` + + Path to the file where text should be inserted + +### Beta Memory Tool 20250818 Rename Command + +- `beta_memory_tool_20250818_rename_command: object { command, new_path, old_path }` + + - `command: "rename"` + + Command type identifier + + - `new_path: string` + + New path for the file or directory + + - `old_path: string` + + Current path of the file or directory + +### Beta Memory Tool 20250818 Str Replace Command + +- `beta_memory_tool_20250818_str_replace_command: object { command, new_str, old_str, path }` + + - `command: "str_replace"` + + Command type identifier + + - `new_str: string` + + Text to replace with + + - `old_str: string` + + Text to search for and replace + + - `path: string` + + Path to the file where text should be replaced + +### Beta Memory Tool 20250818 View Command + +- `beta_memory_tool_20250818_view_command: object { command, path, view_range }` + + - `command: "view"` + + Command type identifier + + - `path: string` + + Path to directory or file to view + + - `view_range: optional array of number` + + Optional line range for viewing specific lines + +### Beta Message + +- `beta_message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + +### Beta Message Delta Usage + +- `beta_message_delta_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 3 more }` + + - `cache_creation_input_tokens: number` + + The cumulative number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The cumulative number of input tokens read from the cache. + + - `input_tokens: number` + + The cumulative number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The cumulative number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + +### Beta Message Iteration Usage + +- `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + +### Beta Message Param + +- `beta_message_param: object { content, role }` + + - `content: array of BetaContentBlockParam` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_request_document_block: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `beta_search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `beta_thinking_block_param: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block_param: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `beta_request_document_block: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `beta_tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + + - `beta_server_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: array of BetaWebSearchResultBlockParam or BetaWebSearchToolRequestError` + + - `Result Block: array of BetaWebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `beta_web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam` + + - `beta_web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaCodeExecutionToolResultErrorParam or BetaCodeExecutionResultBlockParam or BetaEncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_bash_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam` + + - `beta_bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_text_editor_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam` + + - `beta_text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `beta_text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `beta_text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_tool_search_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam` + + - `beta_tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_mcp_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_request_mcp_tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional string or array of BetaTextBlockParam` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_param_content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `is_error: optional boolean` + + - `beta_container_upload_block_param: object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_compaction_block_param: object { content, type, cache_control }` + + A compaction block containing summary of previous context. + + Users should round-trip these blocks from responses to subsequent requests + to maintain context across compaction boundaries. + + When content is None, the block represents a failed compaction. The server + treats these as no-ops. Empty string content is not allowed. + + - `content: string` + + Summary of previously compacted content, or null if compaction failed + + - `type: "compaction"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `role: "user" or "assistant"` + + - `"user"` + + - `"assistant"` + +### Beta Message Tokens Count + +- `beta_message_tokens_count: object { context_management, input_tokens }` + + - `context_management: object { original_input_tokens }` + + Information about context management applied to the message. + + - `original_input_tokens: number` + + The original token count before context management was applied + + - `input_tokens: number` + + The total number of tokens across the provided list of messages, system prompt, and tools. + +### Beta Metadata + +- `beta_metadata: object { user_id }` + + - `user_id: optional string` + + An external identifier for the user who is associated with the request. + + This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. + +### Beta Output Config + +- `beta_output_config: object { effort, format }` + + - `effort: optional "low" or "medium" or "high" or "max"` + + All possible effort levels. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"max"` + + - `format: optional object { schema, type }` + + A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + - `schema: map[unknown]` + + The JSON schema of the format + + - `type: "json_schema"` + +### Beta Plain Text Source + +- `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + +### Beta Raw Content Block Delta + +- `beta_raw_content_block_delta: BetaTextDelta or BetaInputJSONDelta or BetaCitationsDelta or 3 more` + + - `beta_text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + + - `beta_input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + + - `beta_citations_delta: object { citation, type }` + + - `citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more` + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + + - `beta_thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + + - `beta_signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + + - `beta_compaction_content_block_delta: object { content, type }` + + - `content: string` + + - `type: "compaction_delta"` + +### Beta Raw Content Block Delta Event + +- `beta_raw_content_block_delta_event: object { delta, index, type }` + + - `delta: BetaTextDelta or BetaInputJSONDelta or BetaCitationsDelta or 3 more` + + - `beta_text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + + - `beta_input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + + - `beta_citations_delta: object { citation, type }` + + - `citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more` + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + + - `beta_thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + + - `beta_signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + + - `beta_compaction_content_block_delta: object { content, type }` + + - `content: string` + + - `type: "compaction_delta"` + + - `index: number` + + - `type: "content_block_delta"` + +### Beta Raw Content Block Start Event + +- `beta_raw_content_block_start_event: object { content_block, index, type }` + + - `content_block: BetaTextBlock or BetaThinkingBlock or BetaRedactedThinkingBlock or 12 more` + + Response model for a file uploaded to the container. + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `index: number` + + - `type: "content_block_start"` + +### Beta Raw Content Block Stop Event + +- `beta_raw_content_block_stop_event: object { index, type }` + + - `index: number` + + - `type: "content_block_stop"` + +### Beta Raw Message Delta Event + +- `beta_raw_message_delta_event: object { context_management, delta, type, usage }` + + - `context_management: object { applied_edits }` + + Information about context management strategies applied during the request + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `delta: object { container, stop_details, stop_reason, stop_sequence }` + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + - `type: "message_delta"` + + - `usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 3 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation_input_tokens: number` + + The cumulative number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The cumulative number of input tokens read from the cache. + + - `input_tokens: number` + + The cumulative number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The cumulative number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + +### Beta Raw Message Start Event + +- `beta_raw_message_start_event: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "message_start"` + +### Beta Raw Message Stop Event + +- `beta_raw_message_stop_event: object { type }` + + - `type: "message_stop"` + +### Beta Raw Message Stream Event + +- `beta_raw_message_stream_event: BetaRawMessageStartEvent or BetaRawMessageDeltaEvent or BetaRawMessageStopEvent or 3 more` + + - `beta_raw_message_start_event: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "message_start"` + + - `beta_raw_message_delta_event: object { context_management, delta, type, usage }` + + - `context_management: object { applied_edits }` + + Information about context management strategies applied during the request + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `delta: object { container, stop_details, stop_reason, stop_sequence }` + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + - `type: "message_delta"` + + - `usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 3 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation_input_tokens: number` + + The cumulative number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The cumulative number of input tokens read from the cache. + + - `input_tokens: number` + + The cumulative number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The cumulative number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `beta_raw_message_stop_event: object { type }` + + - `type: "message_stop"` + + - `beta_raw_content_block_start_event: object { content_block, index, type }` + + - `content_block: BetaTextBlock or BetaThinkingBlock or BetaRedactedThinkingBlock or 12 more` + + Response model for a file uploaded to the container. + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `index: number` + + - `type: "content_block_start"` + + - `beta_raw_content_block_delta_event: object { delta, index, type }` + + - `delta: BetaTextDelta or BetaInputJSONDelta or BetaCitationsDelta or 3 more` + + - `beta_text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + + - `beta_input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + + - `beta_citations_delta: object { citation, type }` + + - `citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more` + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + + - `beta_thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + + - `beta_signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + + - `beta_compaction_content_block_delta: object { content, type }` + + - `content: string` + + - `type: "compaction_delta"` + + - `index: number` + + - `type: "content_block_delta"` + + - `beta_raw_content_block_stop_event: object { index, type }` + + - `index: number` + + - `type: "content_block_stop"` + +### Beta Redacted Thinking Block + +- `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + +### Beta Redacted Thinking Block Param + +- `beta_redacted_thinking_block_param: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + +### Beta Refusal Stop Details + +- `beta_refusal_stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + +### Beta Request Document Block + +- `beta_request_document_block: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + +### Beta Request MCP Server Tool Configuration + +- `beta_request_mcp_server_tool_configuration: object { allowed_tools, enabled }` + + - `allowed_tools: optional array of string` + + - `enabled: optional boolean` + +### Beta Request MCP Server URL Definition + +- `beta_request_mcp_server_url_definition: object { name, type, url, 2 more }` + + - `name: string` + + - `type: "url"` + + - `url: string` + + - `authorization_token: optional string` + + - `tool_configuration: optional object { allowed_tools, enabled }` + + - `allowed_tools: optional array of string` + + - `enabled: optional boolean` + +### Beta Request MCP Tool Result Block Param + +- `beta_request_mcp_tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional string or array of BetaTextBlockParam` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_param_content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `is_error: optional boolean` + +### Beta Search Result Block Param + +- `beta_search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + +### Beta Server Tool Caller + +- `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + +### Beta Server Tool Caller 20260120 + +- `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Server Tool Usage + +- `beta_server_tool_usage: object { web_fetch_requests, web_search_requests }` + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + +### Beta Server Tool Use Block + +- `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Server Tool Use Block Param + +- `beta_server_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Signature Delta + +- `beta_signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + +### Beta Skill + +- `beta_skill: object { skill_id, type, version }` + + A skill that was loaded in a container (response model). + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + +### Beta Skill Params + +- `beta_skill_params: object { skill_id, type, version }` + + Specification for a skill to be loaded in a container (request model). + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: optional string` + + Skill version or 'latest' for most recent version + +### Beta Stop Reason + +- `beta_stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + +### Beta Text Block + +- `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + +### Beta Text Block Param + +- `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Beta Text Citation + +- `beta_text_citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more` + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Beta Text Citation Param + +- `beta_text_citation_param: BetaCitationCharLocationParam or BetaCitationPageLocationParam or BetaCitationContentBlockLocationParam or 2 more` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Beta Text Delta + +- `beta_text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + +### Beta Text Editor Code Execution Create Result Block + +- `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + +### Beta Text Editor Code Execution Create Result Block Param + +- `beta_text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + +### Beta Text Editor Code Execution Str Replace Result Block + +- `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + +### Beta Text Editor Code Execution Str Replace Result Block Param + +- `beta_text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + +### Beta Text Editor Code Execution Tool Result Block + +- `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + +### Beta Text Editor Code Execution Tool Result Block Param + +- `beta_text_editor_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam` + + - `beta_text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `beta_text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `beta_text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Text Editor Code Execution Tool Result Error + +- `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + +### Beta Text Editor Code Execution Tool Result Error Param + +- `beta_text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + +### Beta Text Editor Code Execution View Result Block + +- `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + +### Beta Text Editor Code Execution View Result Block Param + +- `beta_text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + +### Beta Thinking Block + +- `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + +### Beta Thinking Block Param + +- `beta_thinking_block_param: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + +### Beta Thinking Config Adaptive + +- `beta_thinking_config_adaptive: object { type, display }` + + - `type: "adaptive"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +### Beta Thinking Config Disabled + +- `beta_thinking_config_disabled: object { type }` + + - `type: "disabled"` + +### Beta Thinking Config Enabled + +- `beta_thinking_config_enabled: object { budget_tokens, type, display }` + + - `budget_tokens: number` + + Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. + + Must be ≥1024 and less than `max_tokens`. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `type: "enabled"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +### Beta Thinking Config Param + +- `beta_thinking_config_param: BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigAdaptive` + + Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `beta_thinking_config_enabled: object { budget_tokens, type, display }` + + - `budget_tokens: number` + + Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. + + Must be ≥1024 and less than `max_tokens`. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `type: "enabled"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + + - `beta_thinking_config_disabled: object { type }` + + - `type: "disabled"` + + - `beta_thinking_config_adaptive: object { type, display }` + + - `type: "adaptive"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +### Beta Thinking Delta + +- `beta_thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + +### Beta Thinking Turns + +- `beta_thinking_turns: object { type, value }` + + - `type: "thinking_turns"` + + - `value: number` + +### Beta Tool + +- `beta_tool: object { input_schema, name, allowed_callers, 7 more }` + + - `input_schema: object { type, properties, required }` + + [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + + This defines the shape of the `input` that your tool accepts and that the model will produce. + + - `type: "object"` + + - `properties: optional map[unknown]` + + - `required: optional array of string` + + - `name: string` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `description: optional string` + + Description of what this tool does. + + Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + + - `eager_input_streaming: optional boolean` + + Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `type: optional "custom"` + + - `"custom"` + +### Beta Tool Bash 20241022 + +- `beta_tool_bash_20241022: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20241022"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Bash 20250124 + +- `beta_tool_bash_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Choice + +- `beta_tool_choice: BetaToolChoiceAuto or BetaToolChoiceAny or BetaToolChoiceTool or BetaToolChoiceNone` + + How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + + - `beta_tool_choice_auto: object { type, disable_parallel_tool_use }` + + The model will automatically decide whether to use tools. + + - `type: "auto"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output at most one tool use. + + - `beta_tool_choice_any: object { type, disable_parallel_tool_use }` + + The model will use any available tools. + + - `type: "any"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + + - `beta_tool_choice_tool: object { name, type, disable_parallel_tool_use }` + + The model will use the specified tool with `tool_choice.name`. + + - `name: string` + + The name of the tool to use. + + - `type: "tool"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + + - `beta_tool_choice_none: object { type }` + + The model will not be allowed to use tools. + + - `type: "none"` + +### Beta Tool Choice Any + +- `beta_tool_choice_any: object { type, disable_parallel_tool_use }` + + The model will use any available tools. + + - `type: "any"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + +### Beta Tool Choice Auto + +- `beta_tool_choice_auto: object { type, disable_parallel_tool_use }` + + The model will automatically decide whether to use tools. + + - `type: "auto"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output at most one tool use. + +### Beta Tool Choice None + +- `beta_tool_choice_none: object { type }` + + The model will not be allowed to use tools. + + - `type: "none"` + +### Beta Tool Choice Tool + +- `beta_tool_choice_tool: object { name, type, disable_parallel_tool_use }` + + The model will use the specified tool with `tool_choice.name`. + + - `name: string` + + The name of the tool to use. + + - `type: "tool"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + +### Beta Tool Computer Use 20241022 + +- `beta_tool_computer_use_20241022: object { display_height_px, display_width_px, name, 7 more }` + + - `display_height_px: number` + + The height of the display in pixels. + + - `display_width_px: number` + + The width of the display in pixels. + + - `name: "computer"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "computer_20241022"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `display_number: optional number` + + The X11 display number (e.g. 0, 1) for the display. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Computer Use 20250124 + +- `beta_tool_computer_use_20250124: object { display_height_px, display_width_px, name, 7 more }` + + - `display_height_px: number` + + The height of the display in pixels. + + - `display_width_px: number` + + The width of the display in pixels. + + - `name: "computer"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "computer_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `display_number: optional number` + + The X11 display number (e.g. 0, 1) for the display. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Computer Use 20251124 + +- `beta_tool_computer_use_20251124: object { display_height_px, display_width_px, name, 8 more }` + + - `display_height_px: number` + + The height of the display in pixels. + + - `display_width_px: number` + + The width of the display in pixels. + + - `name: "computer"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "computer_20251124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `display_number: optional number` + + The X11 display number (e.g. 0, 1) for the display. + + - `enable_zoom: optional boolean` + + Whether to enable an action to take a zoomed-in screenshot of the screen. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Reference Block + +- `beta_tool_reference_block: object { tool_name, type }` + + - `tool_name: string` + + - `type: "tool_reference"` + +### Beta Tool Reference Block Param + +- `beta_tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Tool Result Block Param + +- `beta_tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `beta_search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of BetaTextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `beta_request_document_block: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `beta_tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + +### Beta Tool Search Tool Bm25 20251119 + +- `beta_tool_search_tool_bm25_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_bm25"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + + - `"tool_search_tool_bm25"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Search Tool Regex 20251119 + +- `beta_tool_search_tool_regex_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_regex"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + + - `"tool_search_tool_regex"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Search Tool Result Block + +- `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + +### Beta Tool Search Tool Result Block Param + +- `beta_tool_search_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam` + + - `beta_tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Beta Tool Search Tool Result Error + +- `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + +### Beta Tool Search Tool Result Error Param + +- `beta_tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + +### Beta Tool Search Tool Search Result Block + +- `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + +### Beta Tool Search Tool Search Result Block Param + +- `beta_tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + +### Beta Tool Text Editor 20241022 + +- `beta_tool_text_editor_20241022: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20241022"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Text Editor 20250124 + +- `beta_tool_text_editor_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Text Editor 20250429 + +- `beta_tool_text_editor_20250429: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250429"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Text Editor 20250728 + +- `beta_tool_text_editor_20250728: object { name, type, allowed_callers, 5 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250728"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `max_characters: optional number` + + Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Tool Union + +- `beta_tool_union: BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 19 more` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `beta_tool: object { input_schema, name, allowed_callers, 7 more }` + + - `input_schema: object { type, properties, required }` + + [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + + This defines the shape of the `input` that your tool accepts and that the model will produce. + + - `type: "object"` + + - `properties: optional map[unknown]` + + - `required: optional array of string` + + - `name: string` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `description: optional string` + + Description of what this tool does. + + Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + + - `eager_input_streaming: optional boolean` + + Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `type: optional "custom"` + + - `"custom"` + + - `beta_tool_bash_20241022: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20241022"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_bash_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_code_execution_tool_20250522: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250522"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_code_execution_tool_20250825: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250825"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_code_execution_tool_20260120: object { name, type, allowed_callers, 3 more }` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20260120"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_computer_use_20241022: object { display_height_px, display_width_px, name, 7 more }` + + - `display_height_px: number` + + The height of the display in pixels. + + - `display_width_px: number` + + The width of the display in pixels. + + - `name: "computer"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "computer_20241022"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `display_number: optional number` + + The X11 display number (e.g. 0, 1) for the display. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_memory_tool_20250818: object { name, type, allowed_callers, 4 more }` + + - `name: "memory"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "memory_20250818"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_computer_use_20250124: object { display_height_px, display_width_px, name, 7 more }` + + - `display_height_px: number` + + The height of the display in pixels. + + - `display_width_px: number` + + The width of the display in pixels. + + - `name: "computer"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "computer_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `display_number: optional number` + + The X11 display number (e.g. 0, 1) for the display. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_text_editor_20241022: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20241022"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_computer_use_20251124: object { display_height_px, display_width_px, name, 8 more }` + + - `display_height_px: number` + + The height of the display in pixels. + + - `display_width_px: number` + + The width of the display in pixels. + + - `name: "computer"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "computer_20251124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `display_number: optional number` + + The X11 display number (e.g. 0, 1) for the display. + + - `enable_zoom: optional boolean` + + Whether to enable an action to take a zoomed-in screenshot of the screen. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_text_editor_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_text_editor_20250429: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250429"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_text_editor_20250728: object { name, type, allowed_callers, 5 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250728"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `max_characters: optional number` + + Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_web_search_tool_20250305: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20250305"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `beta_web_fetch_tool_20250910: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20250910"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_web_search_tool_20260209: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `beta_web_fetch_tool_20260209: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_web_fetch_tool_20260309: object { name, type, allowed_callers, 9 more }` + + Web fetch tool with use_cache parameter for bypassing cached content. + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260309"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `use_cache: optional boolean` + + Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. + + - `beta_tool_search_tool_bm25_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_bm25"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + + - `"tool_search_tool_bm25"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_tool_search_tool_regex_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_regex"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + + - `"tool_search_tool_regex"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `beta_mcp_toolset: object { mcp_server_name, type, cache_control, 2 more }` + + Configuration for a group of tools from an MCP server. + + Allows configuring enabled status and defer_loading for all tools + from an MCP server, with optional per-tool overrides. + + - `mcp_server_name: string` + + Name of the MCP server to configure tools for + + - `type: "mcp_toolset"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `configs: optional map[BetaMCPToolConfig]` + + Configuration overrides for specific tools, keyed by tool name + + - `defer_loading: optional boolean` + + - `enabled: optional boolean` + + - `default_config: optional object { defer_loading, enabled }` + + Default configuration applied to all tools from this server + + - `defer_loading: optional boolean` + + - `enabled: optional boolean` + +### Beta Tool Use Block + +- `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Tool Use Block Param + +- `beta_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Tool Uses Keep + +- `beta_tool_uses_keep: object { type, value }` + + - `type: "tool_uses"` + + - `value: number` + +### Beta Tool Uses Trigger + +- `beta_tool_uses_trigger: object { type, value }` + + - `type: "tool_uses"` + + - `value: number` + +### Beta URL Image Source + +- `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + +### Beta URL PDF Source + +- `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + +### Beta Usage + +- `beta_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + +### Beta User Location + +- `beta_user_location: object { type, city, country, 2 more }` + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + +### Beta Web Fetch Block + +- `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + +### Beta Web Fetch Block Param + +- `beta_web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + +### Beta Web Fetch Tool 20250910 + +- `beta_web_fetch_tool_20250910: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20250910"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Web Fetch Tool 20260209 + +- `beta_web_fetch_tool_20260209: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Beta Web Fetch Tool 20260309 + +- `beta_web_fetch_tool_20260309: object { name, type, allowed_callers, 9 more }` + + Web fetch tool with use_cache parameter for bypassing cached content. + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260309"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `use_cache: optional boolean` + + Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. + +### Beta Web Fetch Tool Result Block + +- `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Web Fetch Tool Result Block Param + +- `beta_web_fetch_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam` + + - `beta_web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `beta_content_block_source: object { content, type }` + + - `content: string or array of BetaContentBlockSourceContent` + + - `union_member_0: string` + + - `beta_content_block_source_content: array of BetaContentBlockSourceContent` + + - `beta_text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of BetaTextCitationParam` + + - `beta_citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `beta_image_block_param: object { source, type, cache_control }` + + - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` + + - `beta_base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `beta_url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_image_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `beta_url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `beta_file_document_source: object { file_id, type }` + + - `file_id: string` + + - `type: "file"` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Web Fetch Tool Result Error Block + +- `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + +### Beta Web Fetch Tool Result Error Block Param + +- `beta_web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + +### Beta Web Fetch Tool Result Error Code + +- `beta_web_fetch_tool_result_error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + +### Beta Web Search Result Block + +- `beta_web_search_result_block: object { encrypted_content, page_age, title, 2 more }` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + +### Beta Web Search Result Block Param + +- `beta_web_search_result_block_param: object { encrypted_content, title, type, 2 more }` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + +### Beta Web Search Tool 20250305 + +- `beta_web_search_tool_20250305: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20250305"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + +### Beta Web Search Tool 20260209 + +- `beta_web_search_tool_20260209: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + +### Beta Web Search Tool Request Error + +- `beta_web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + +### Beta Web Search Tool Result Block + +- `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Web Search Tool Result Block Content + +- `beta_web_search_tool_result_block_content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + +### Beta Web Search Tool Result Block Param + +- `beta_web_search_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: array of BetaWebSearchResultBlockParam or BetaWebSearchToolRequestError` + + - `Result Block: array of BetaWebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `beta_web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Beta Web Search Tool Result Block Param Content + +- `beta_web_search_tool_result_block_param_content: array of BetaWebSearchResultBlockParam or BetaWebSearchToolRequestError` + + - `Result Block: array of BetaWebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `beta_web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + +### Beta Web Search Tool Result Error + +- `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + +### Beta Web Search Tool Result Error Code + +- `beta_web_search_tool_result_error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + +# Batches + +## Create + +`$ ant beta:messages:batches create` + +**post** `/v1/messages/batches` + +Send a batch of Message creation requests. + +The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--request: array of object { custom_id, params }` + + Body param: List of requests for prompt completion. Each is an individual request to create a Message. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant beta:messages:batches create \ + --api-key my-anthropic-api-key \ + --request '{custom_id: my-custom-id-1, params: {max_tokens: 1024, messages: [{content: [{text: x, type: text}], role: user}], model: claude-opus-4-6}}' +``` + +## Retrieve + +`$ ant beta:messages:batches retrieve` + +**get** `/v1/messages/batches/{message_batch_id}` + +This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant beta:messages:batches retrieve \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## List + +`$ ant beta:messages:batches list` + +**get** `/v1/messages/batches` + +List all Message Batches within a Workspace. Most recently created batches are returned first. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListResponse_MessageBatch_: object { data, first_id, has_more, last_id }` + + - `data: array of BetaMessageBatch` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant beta:messages:batches list \ + --api-key my-anthropic-api-key +``` + +## Cancel + +`$ ant beta:messages:batches cancel` + +**post** `/v1/messages/batches/{message_batch_id}/cancel` + +Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. + +The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant beta:messages:batches cancel \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Delete + +`$ ant beta:messages:batches delete` + +**delete** `/v1/messages/batches/{message_batch_id}` + +Delete a Message Batch. + +Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Example + +```cli +ant beta:messages:batches delete \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Results + +`$ ant beta:messages:batches results` + +**get** `/v1/messages/batches/{message_batch_id}/results` + +Streams the results of a Message Batch as a `.jsonl` file. + +Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` + + - `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Example + +```cli +ant beta:messages:batches results \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Domain Types + +### Beta Deleted Message Batch + +- `beta_deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Beta Message Batch + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Beta Message Batch Canceled Result + +- `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + +### Beta Message Batch Errored Result + +- `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + +### Beta Message Batch Expired Result + +- `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Beta Message Batch Individual Response + +- `beta_message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` + + - `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Beta Message Batch Request Counts + +- `beta_message_batch_request_counts: object { canceled, errored, expired, 2 more }` + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + +### Beta Message Batch Result + +- `beta_message_batch_result: BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` + + - `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Beta Message Batch Succeeded Result + +- `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` diff --git a/content/en/api/cli/beta/messages/batches.md b/content/en/api/cli/beta/messages/batches.md index 21907b0d4..337681201 100644 --- a/content/en/api/cli/beta/messages/batches.md +++ b/content/en/api/cli/beta/messages/batches.md @@ -1 +1,5402 @@ -Not Found - Claude API Docs
                    \ No newline at end of file +# Batches + +## Create + +`$ ant beta:messages:batches create` + +**post** `/v1/messages/batches` + +Send a batch of Message creation requests. + +The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--request: array of object { custom_id, params }` + + Body param: List of requests for prompt completion. Each is an individual request to create a Message. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant beta:messages:batches create \ + --api-key my-anthropic-api-key \ + --request '{custom_id: my-custom-id-1, params: {max_tokens: 1024, messages: [{content: [{text: x, type: text}], role: user}], model: claude-opus-4-6}}' +``` + +## Retrieve + +`$ ant beta:messages:batches retrieve` + +**get** `/v1/messages/batches/{message_batch_id}` + +This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant beta:messages:batches retrieve \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## List + +`$ ant beta:messages:batches list` + +**get** `/v1/messages/batches` + +List all Message Batches within a Workspace. Most recently created batches are returned first. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListResponse_MessageBatch_: object { data, first_id, has_more, last_id }` + + - `data: array of BetaMessageBatch` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant beta:messages:batches list \ + --api-key my-anthropic-api-key +``` + +## Cancel + +`$ ant beta:messages:batches cancel` + +**post** `/v1/messages/batches/{message_batch_id}/cancel` + +Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. + +The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant beta:messages:batches cancel \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Delete + +`$ ant beta:messages:batches delete` + +**delete** `/v1/messages/batches/{message_batch_id}` + +Delete a Message Batch. + +Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Example + +```cli +ant beta:messages:batches delete \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Results + +`$ ant beta:messages:batches results` + +**get** `/v1/messages/batches/{message_batch_id}/results` + +Streams the results of a Message Batch as a `.jsonl` file. + +Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` + + - `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Example + +```cli +ant beta:messages:batches results \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Domain Types + +### Beta Deleted Message Batch + +- `beta_deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Beta Message Batch + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Beta Message Batch Canceled Result + +- `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + +### Beta Message Batch Errored Result + +- `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + +### Beta Message Batch Expired Result + +- `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Beta Message Batch Individual Response + +- `beta_message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` + + - `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Beta Message Batch Request Counts + +- `beta_message_batch_request_counts: object { canceled, errored, expired, 2 more }` + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + +### Beta Message Batch Result + +- `beta_message_batch_result: BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` + + - `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Beta Message Batch Succeeded Result + +- `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` diff --git a/content/en/api/cli/beta/messages/batches/cancel.md b/content/en/api/cli/beta/messages/batches/cancel.md index 34f803607..d35ceb563 100644 --- a/content/en/api/cli/beta/messages/batches/cancel.md +++ b/content/en/api/cli/beta/messages/batches/cancel.md @@ -1 +1,117 @@ -Not Found - Claude API Docs
                      \ No newline at end of file +## Cancel + +`$ ant beta:messages:batches cancel` + +**post** `/v1/messages/batches/{message_batch_id}/cancel` + +Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. + +The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant beta:messages:batches cancel \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` diff --git a/content/en/api/cli/beta/messages/batches/create.md b/content/en/api/cli/beta/messages/batches/create.md index e7133e01b..6484771fb 100644 --- a/content/en/api/cli/beta/messages/batches/create.md +++ b/content/en/api/cli/beta/messages/batches/create.md @@ -1 +1,117 @@ -Not Found - Claude API Docs
                        \ No newline at end of file +## Create + +`$ ant beta:messages:batches create` + +**post** `/v1/messages/batches` + +Send a batch of Message creation requests. + +The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--request: array of object { custom_id, params }` + + Body param: List of requests for prompt completion. Each is an individual request to create a Message. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant beta:messages:batches create \ + --api-key my-anthropic-api-key \ + --request '{custom_id: my-custom-id-1, params: {max_tokens: 1024, messages: [{content: [{text: x, type: text}], role: user}], model: claude-opus-4-6}}' +``` diff --git a/content/en/api/cli/beta/messages/batches/delete.md b/content/en/api/cli/beta/messages/batches/delete.md index 09246687f..12b3f5b4d 100644 --- a/content/en/api/cli/beta/messages/batches/delete.md +++ b/content/en/api/cli/beta/messages/batches/delete.md @@ -1 +1,43 @@ -Not Found - Claude API Docs
                          \ No newline at end of file +## Delete + +`$ ant beta:messages:batches delete` + +**delete** `/v1/messages/batches/{message_batch_id}` + +Delete a Message Batch. + +Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Example + +```cli +ant beta:messages:batches delete \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` diff --git a/content/en/api/cli/beta/messages/batches/list.md b/content/en/api/cli/beta/messages/batches/list.md index e6c80d8df..063832a75 100644 --- a/content/en/api/cli/beta/messages/batches/list.md +++ b/content/en/api/cli/beta/messages/batches/list.md @@ -1 +1,138 @@ -Not Found - Claude API Docs
                            \ No newline at end of file +## List + +`$ ant beta:messages:batches list` + +**get** `/v1/messages/batches` + +List all Message Batches within a Workspace. Most recently created batches are returned first. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListResponse_MessageBatch_: object { data, first_id, has_more, last_id }` + + - `data: array of BetaMessageBatch` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant beta:messages:batches list \ + --api-key my-anthropic-api-key +``` diff --git a/content/en/api/cli/beta/messages/batches/results.md b/content/en/api/cli/beta/messages/batches/results.md index 41b01b9f6..3e9eb868a 100644 --- a/content/en/api/cli/beta/messages/batches/results.md +++ b/content/en/api/cli/beta/messages/batches/results.md @@ -1 +1,1209 @@ -Not Found - Claude API Docs
                              \ No newline at end of file +## Results + +`$ ant beta:messages:batches results` + +**get** `/v1/messages/batches/{message_batch_id}/results` + +Streams the results of a Message Batch as a `.jsonl` file. + +Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `beta_message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + + - `type: "succeeded"` + + - `beta_message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` + + - `beta_invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `beta_authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `beta_billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `beta_permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `beta_not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `beta_rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `beta_gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `beta_api_error: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `beta_overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `beta_message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `beta_message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Example + +```cli +ant beta:messages:batches results \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` diff --git a/content/en/api/cli/beta/messages/batches/retrieve.md b/content/en/api/cli/beta/messages/batches/retrieve.md index 99d190af7..6ab5cd4a0 100644 --- a/content/en/api/cli/beta/messages/batches/retrieve.md +++ b/content/en/api/cli/beta/messages/batches/retrieve.md @@ -1 +1,115 @@ -Not Found - Claude API Docs
                                \ No newline at end of file +## Retrieve + +`$ ant beta:messages:batches retrieve` + +**get** `/v1/messages/batches/{message_batch_id}` + +This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant beta:messages:batches retrieve \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` diff --git a/content/en/api/cli/beta/messages/count_tokens.md b/content/en/api/cli/beta/messages/count_tokens.md index c8646c0dc..3f3116683 100644 --- a/content/en/api/cli/beta/messages/count_tokens.md +++ b/content/en/api/cli/beta/messages/count_tokens.md @@ -1 +1,209 @@ -Not Found - Claude API Docs
                                  \ No newline at end of file +## Count Tokens + +`$ ant beta:messages count-tokens` + +**post** `/v1/messages/count_tokens` + +Count the number of tokens in a Message. + +The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it. + +Learn more about token counting in our [user guide](https://docs.claude.com/en/docs/build-with-claude/token-counting) + +### Parameters + +- `--message: array of BetaMessageParam` + + Body param: Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + +- `--model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + Body param: The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--cache-control: optional object { type, ttl }` + + Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--context-management: optional object { edits }` + + Body param: Context management configuration. + + This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. + +- `--mcp-server: optional array of BetaRequestMCPServerURLDefinition` + + Body param: MCP servers to be utilized in this request + +- `--output-config: optional object { effort, format }` + + Body param: Configuration options for the model's output, such as the output format. + +- `--output-format: optional object { schema, type }` + + Body param: Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + A schema to specify Claude's output format in responses. This parameter will be removed in a future release. + +- `--speed: optional "standard" or "fast"` + + Body param: The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. + +- `--system: optional string or array of BetaTextBlockParam` + + Body param: System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + +- `--thinking: optional BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigAdaptive` + + Body param: Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + +- `--tool-choice: optional BetaToolChoiceAuto or BetaToolChoiceAny or BetaToolChoiceTool or BetaToolChoiceNone` + + Body param: How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + +- `--tool: optional array of BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 19 more` + + Body param: Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message_tokens_count: object { context_management, input_tokens }` + + - `context_management: object { original_input_tokens }` + + Information about context management applied to the message. + + - `original_input_tokens: number` + + The original token count before context management was applied + + - `input_tokens: number` + + The total number of tokens across the provided list of messages, system prompt, and tools. + +### Example + +```cli +ant beta:messages count-tokens \ + --api-key my-anthropic-api-key \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-mythos-preview +``` diff --git a/content/en/api/cli/beta/messages/create.md b/content/en/api/cli/beta/messages/create.md index 2ec4bced0..5476cbeef 100644 --- a/content/en/api/cli/beta/messages/create.md +++ b/content/en/api/cli/beta/messages/create.md @@ -1 +1,1338 @@ -Not Found - Claude API Docs
                                    \ No newline at end of file +## Create + +`$ ant beta:messages create` + +**post** `/v1/messages` + +Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. + +The Messages API can be used for either single queries or stateless multi-turn conversations. + +Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup) + +### Parameters + +- `--max-tokens: number` + + Body param: The maximum number of tokens to generate before stopping. + + Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. + + Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. + +- `--message: array of BetaMessageParam` + + Body param: Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + +- `--model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + Body param: The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--cache-control: optional object { type, ttl }` + + Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--container: optional BetaContainerParams or string` + + Body param: Container identifier for reuse across requests. + +- `--context-management: optional object { edits }` + + Body param: Context management configuration. + + This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. + +- `--inference-geo: optional string` + + Body param: Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. + +- `--mcp-server: optional array of BetaRequestMCPServerURLDefinition` + + Body param: MCP servers to be utilized in this request + +- `--metadata: optional object { user_id }` + + Body param: An object describing metadata about the request. + +- `--output-config: optional object { effort, format }` + + Body param: Configuration options for the model's output, such as the output format. + +- `--output-format: optional object { schema, type }` + + Body param: Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + A schema to specify Claude's output format in responses. This parameter will be removed in a future release. + +- `--service-tier: optional "auto" or "standard_only"` + + Body param: Determines whether to use priority capacity (if available) or standard capacity for this request. + + Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. + +- `--speed: optional "standard" or "fast"` + + Body param: The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. + +- `--stop-sequence: optional array of string` + + Body param: Custom text sequences that will cause the model to stop generating. + + Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. + + If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. + +- `--system: optional string or array of BetaTextBlockParam` + + Body param: System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + +- `--temperature: optional number` + + Body param: Amount of randomness injected into the response. + + Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. + + Note that even with `temperature` of `0.0`, the results will not be fully deterministic. + +- `--thinking: optional BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigAdaptive` + + Body param: Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + +- `--tool-choice: optional BetaToolChoiceAuto or BetaToolChoiceAny or BetaToolChoiceTool or BetaToolChoiceNone` + + Body param: How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + +- `--tool: optional array of BetaToolUnion` + + Body param: Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + +- `--top-k: optional number` + + Body param: Only sample from the top K options for each subsequent token. + + Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--top-p: optional number` + + Body param: Use nucleus sampling. + + In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_message: object { id, container, content, 8 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at, skills }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `skills: array of BetaSkill` + + Skills loaded in the container + + - `skill_id: string` + + Skill ID + + - `type: "anthropic" or "custom"` + + Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) + + - `"anthropic"` + + - `"custom"` + + - `version: string` + + Skill version or 'latest' for most recent version + + - `content: array of BetaContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `beta_text_block: object { citations, text, type }` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `beta_thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `beta_redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `beta_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_server_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_search_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` + + - `beta_web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of BetaWebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_web_fetch_tool_result_block: object { content, tool_use_id, type, caller }` + + - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` + + - `beta_web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `beta_web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: BetaBase64PDFSource or BetaPlainTextSource` + + - `beta_base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `beta_plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` + + Tool invocation directly from the model. + + - `beta_direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `beta_server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `beta_server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `beta_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `beta_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `beta_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `beta_encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of BetaCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `beta_bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` + + - `beta_bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `beta_bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BetaBashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `beta_text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` + + - `beta_text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `beta_text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `beta_text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `beta_text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `beta_tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` + + - `beta_tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `beta_tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of BetaToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `beta_mcp_tool_use_block: object { id, input, name, 2 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + The name of the MCP tool + + - `server_name: string` + + The name of the MCP server + + - `type: "mcp_tool_use"` + + - `beta_mcp_tool_result_block: object { content, is_error, tool_use_id, type }` + + - `content: string or array of BetaTextBlock` + + - `union_member_0: string` + + - `beta_mcp_tool_result_block_content: array of BetaTextBlock` + + - `citations: array of BetaTextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `beta_citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `beta_citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `beta_citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `beta_citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `beta_citation_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `is_error: boolean` + + - `tool_use_id: string` + + - `type: "mcp_tool_result"` + + - `beta_container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `beta_compaction_block: object { content, type }` + + A compaction block returned when autocompact is triggered. + + When content is None, it indicates the compaction failed to produce a valid + summary (e.g., malformed output from the model). Clients may round-trip + compaction blocks with null content; the server treats them as no-ops. + + - `content: string` + + Summary of compacted content, or null if compaction failed + + - `type: "compaction"` + + - `context_management: object { applied_edits }` + + Context management response. + + Information about context management strategies applied during the request. + + - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` + + List of context management edits that were applied. + + - `beta_clear_tool_uses_20250919_edit_response: object { cleared_input_tokens, cleared_tool_uses, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_tool_uses: number` + + Number of tool uses that were cleared. + + - `type: "clear_tool_uses_20250919"` + + The type of context management edit applied. + + - `beta_clear_thinking_20251015_edit_response: object { cleared_input_tokens, cleared_thinking_turns, type }` + + - `cleared_input_tokens: number` + + Number of input tokens cleared by this edit. + + - `cleared_thinking_turns: number` + + Number of thinking turns that were cleared. + + - `type: "clear_thinking_20251015"` + + The type of context management edit applied. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"compaction"` + + - `"refusal"` + + - `"model_context_window_exceeded"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage` + + Per-iteration token usage breakdown. + + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + + - Determine which iterations exceeded long context thresholds (>=200k tokens) + - Calculate the true context window size from the last iteration + - Understand token accumulation across server-side tool use loops + + - `beta_message_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a sampling iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "message"` + + Usage for a sampling iteration + + - `beta_compaction_iteration_usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` + + Token usage for a compaction iteration. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `type: "compaction"` + + Usage for a compaction iteration + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `speed: "standard" or "fast"` + + The inference speed mode used for this request. + + - `"standard"` + + - `"fast"` + +### Example + +```cli +ant beta:messages create \ + --api-key my-anthropic-api-key \ + --max-tokens 1024 \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-opus-4-6 +``` diff --git a/content/en/api/cli/beta/models.md b/content/en/api/cli/beta/models.md index b49b133e5..9a2649b75 100644 --- a/content/en/api/cli/beta/models.md +++ b/content/en/api/cli/beta/models.md @@ -1 +1,920 @@ -Not Found - Claude API Docs
                                      \ No newline at end of file +# Models + +## List + +`$ ant beta:models list` + +**get** `/v1/models` + +List available models. + +The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first. + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListResponse_ModelInfo_: object { data, first_id, has_more, last_id }` + + - `data: array of BetaModelInfo` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant beta:models list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant beta:models retrieve` + +**get** `/v1/models/{model_id}` + +Get a specific model. + +The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID. + +### Parameters + +- `--model-id: string` + + Model identifier or alias. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_model_info: object { id, capabilities, created_at, 4 more }` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + +### Example + +```cli +ant beta:models retrieve \ + --api-key my-anthropic-api-key \ + --model-id model_id +``` + +## Domain Types + +### Beta Capability Support + +- `beta_capability_support: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Beta Context Management Capability + +- `beta_context_management_capability: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management capability details. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Beta Effort Capability + +- `beta_effort_capability: object { high, low, max, 2 more }` + + Effort (reasoning_effort) capability details. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Beta Model Capabilities + +- `beta_model_capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Beta Model Info + +- `beta_model_info: object { id, capabilities, created_at, 4 more }` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + +### Beta Thinking Capability + +- `beta_thinking_capability: object { supported, types }` + + Thinking capability details. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Beta Thinking Types + +- `beta_thinking_types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. diff --git a/content/en/api/cli/beta/models/list.md b/content/en/api/cli/beta/models/list.md index d4238aa95..dd6086bb1 100644 --- a/content/en/api/cli/beta/models/list.md +++ b/content/en/api/cli/beta/models/list.md @@ -1 +1,232 @@ -Not Found - Claude API Docs
                                        \ No newline at end of file +## List + +`$ ant beta:models list` + +**get** `/v1/models` + +List available models. + +The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first. + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListResponse_ModelInfo_: object { data, first_id, has_more, last_id }` + + - `data: array of BetaModelInfo` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant beta:models list \ + --api-key my-anthropic-api-key +``` diff --git a/content/en/api/cli/beta/models/retrieve.md b/content/en/api/cli/beta/models/retrieve.md index 73e3324ff..480fd3578 100644 --- a/content/en/api/cli/beta/models/retrieve.md +++ b/content/en/api/cli/beta/models/retrieve.md @@ -1 +1,209 @@ -Not Found - Claude API Docs
                                          \ No newline at end of file +## Retrieve + +`$ ant beta:models retrieve` + +**get** `/v1/models/{model_id}` + +Get a specific model. + +The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID. + +### Parameters + +- `--model-id: string` + + Model identifier or alias. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_model_info: object { id, capabilities, created_at, 4 more }` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + +### Example + +```cli +ant beta:models retrieve \ + --api-key my-anthropic-api-key \ + --model-id model_id +``` diff --git a/content/en/api/cli/beta/sessions.md b/content/en/api/cli/beta/sessions.md new file mode 100644 index 000000000..c72f94a90 --- /dev/null +++ b/content/en/api/cli/beta/sessions.md @@ -0,0 +1,12932 @@ +# Sessions + +## Create + +`$ ant beta:sessions create` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `--agent: string or BetaManagedAgentsAgentParams` + + Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + +- `--environment-id: string` + + Body param: ID of the `environment` defining the container configuration for this session. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata attached to the session. + +- `--resource: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams` + + Body param: Resources (e.g. repositories, files) to mount into the session's container. + +- `--title: optional string` + + Body param: Human-readable session title. + +- `--vault-id: optional array of string` + + Body param: Vault IDs for stored credentials the agent can use during the session. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```cli +ant beta:sessions create \ + --api-key my-anthropic-api-key \ + --agent agent_011CZkYpogX7uDKUyvBTophP \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` + +## List + +`$ ant beta:sessions list` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `--agent-id: optional string` + + Query param: Filter sessions created with this agent ID. + +- `--agent-version: optional number` + + Query param: Filter by agent version. Only applies when agent_id is also set. + +- `--created-at-gt: optional string` + + Query param: Return sessions created after this time (exclusive). + +- `--created-at-gte: optional string` + + Query param: Return sessions created at or after this time (inclusive). + +- `--created-at-lt: optional string` + + Query param: Return sessions created before this time (exclusive). + +- `--created-at-lte: optional string` + + Query param: Return sessions created at or before this time (inclusive). + +- `--include-archived: optional boolean` + + Query param: When true, includes archived sessions. Default: false (exclude archived). + +- `--limit: optional number` + + Query param: Maximum number of results to return. + +- `--order: optional "asc" or "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). + +- `--page: optional string` + + Query param: Opaque pagination cursor from a previous response's next_page. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListSessions: object { data, next_page }` + + Paginated list of sessions. + + - `data: optional array of BetaManagedAgentsSession` + + List of sessions. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:sessions list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant beta:sessions retrieve` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```cli +ant beta:sessions retrieve \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Update + +`$ ant beta:sessions update` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + +- `--title: optional string` + + Body param: Human-readable session title. + +- `--vault-id: optional array of string` + + Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```cli +ant beta:sessions update \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Delete + +`$ ant beta:sessions delete` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_deleted_session: object { id, type }` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Example + +```cli +ant beta:sessions delete \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Archive + +`$ ant beta:sessions archive` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```cli +ant beta:sessions archive \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `beta_managed_agents_agent_params: object { id, type, version }` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: string` + + The `agent` ID. + + - `type: "agent"` + + - `"agent"` + + - `version: optional number` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + +### Beta Managed Agents Cache Creation Usage + +- `beta_managed_agents_cache_creation_usage: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Deleted Session + +- `beta_managed_agents_deleted_session: object { id, type }` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Beta Managed Agents File Resource Params + +- `beta_managed_agents_file_resource_params: object { file_id, type, mount_path }` + + Mount a file uploaded via the Files API into the session. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `beta_managed_agents_github_repository_resource_params: object { authorization_token, type, url, 2 more }` + + Mount a GitHub repository into the session's container. + + - `authorization_token: string` + + GitHub authorization token used to clone the repository. + + - `type: "github_repository"` + + - `"github_repository"` + + - `url: string` + + Github URL of the repository + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `mount_path: optional string` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `beta_managed_agents_session_agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + +### Beta Managed Agents Session Stats + +- `beta_managed_agents_session_stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `beta_managed_agents_session_usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + +# Events + +## List + +`$ ant beta:sessions:events list` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--limit: optional number` + + Query param: Query parameter for limit + +- `--order: optional "asc" or "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + +- `--page: optional string` + + Query param: Opaque pagination cursor from a previous response's next_page. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListSessionEvents: object { data, next_page }` + + Paginated list of events for a `session`. + + - `data: optional array of BetaManagedAgentsSessionEvent` + + Events for the session, ordered by `created_at`. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:sessions:events list \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Send + +`$ ant beta:sessions:events send` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--event: array of BetaManagedAgentsEventParams` + + Body param: Events to send to the `session`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_send_session_events: object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:events send \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --event "{content: [{text: 'Where is my order #1234?', type: text}], type: user.message}" +``` + +## Stream + +`$ ant beta:sessions:events stream` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_stream_session_events: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```cli +ant beta:sessions:events stream \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Agent Message Event + +- `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Base64 Document Source + +- `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Base64 Image Source + +- `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Billing Error + +- `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + +### Beta Managed Agents Document Block + +- `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + +### Beta Managed Agents Event Params + +- `beta_managed_agents_event_params: BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserInterruptEventParams or BetaManagedAgentsUserToolConfirmationEventParams or BetaManagedAgentsUserCustomToolResultEventParams` + + Union type for event parameters that can be sent to a session. + + - `beta_managed_agents_user_message_event_params: object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `beta_managed_agents_user_interrupt_event_params: object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `beta_managed_agents_user_tool_confirmation_event_params: object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `beta_managed_agents_user_custom_tool_result_event_params: object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents File Image Source + +- `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents Image Block + +- `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Retry Status Exhausted + +- `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + +### Beta Managed Agents Send Session Events + +- `beta_managed_agents_send_session_events: object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + +### Beta Managed Agents Session Error Event + +- `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + +### Beta Managed Agents Session Event + +- `beta_managed_agents_session_event: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Union type for all event types in a session. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `beta_managed_agents_span_model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Stream Session Events + +- `beta_managed_agents_stream_session_events: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Text Block + +- `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Unknown Error + +- `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + +### Beta Managed Agents URL Document Source + +- `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `beta_managed_agents_user_custom_tool_result_event_params: object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `beta_managed_agents_user_interrupt_event_params: object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `beta_managed_agents_user_message_event_params: object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `beta_managed_agents_user_tool_confirmation_event_params: object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`$ ant beta:sessions:resources add` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--file-id: string` + + Body param: ID of a previously uploaded file. + +- `--type: "file"` + + Body param + +- `--mount-path: optional string` + + Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:resources add \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --file-id file_011CNha8iCJcU1wXNR6q4V8w \ + --type file +``` + +## List + +`$ ant beta:sessions:resources list` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--limit: optional number` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `--page: optional string` + + Query param: Opaque cursor from a previous response's next_page field. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListSessionResources: object { data, next_page }` + + Paginated list of resources attached to a session. + + - `data: array of BetaManagedAgentsSessionResource` + + Resources for the session, ordered by `created_at`. + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:sessions:resources list \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Retrieve + +`$ ant beta:sessions:resources retrieve` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--resource-id: string` + + Path param: Path parameter resource_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSessionResourceGetResponse: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The requested session resource. + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:resources retrieve \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht +``` + +## Update + +`$ ant beta:sessions:resources update` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--resource-id: string` + + Path param: Path parameter resource_id + +- `--authorization-token: string` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSessionResourceUpdateResponse: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The updated session resource. + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:resources update \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht \ + --authorization-token ghp_exampletoken +``` + +## Delete + +`$ ant beta:sessions:resources delete` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--resource-id: string` + + Path param: Path parameter resource_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_delete_session_resource: object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Example + +```cli +ant beta:sessions:resources delete \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `beta_managed_agents_delete_session_resource: object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Session Resource + +- `beta_managed_agents_session_resource: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format diff --git a/content/en/api/cli/beta/sessions/archive.md b/content/en/api/cli/beta/sessions/archive.md new file mode 100644 index 000000000..32d02d78f --- /dev/null +++ b/content/en/api/cli/beta/sessions/archive.md @@ -0,0 +1,447 @@ +## Archive + +`$ ant beta:sessions archive` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```cli +ant beta:sessions archive \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` diff --git a/content/en/api/cli/beta/sessions/create.md b/content/en/api/cli/beta/sessions/create.md new file mode 100644 index 000000000..be08c2d34 --- /dev/null +++ b/content/en/api/cli/beta/sessions/create.md @@ -0,0 +1,468 @@ +## Create + +`$ ant beta:sessions create` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `--agent: string or BetaManagedAgentsAgentParams` + + Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + +- `--environment-id: string` + + Body param: ID of the `environment` defining the container configuration for this session. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata attached to the session. + +- `--resource: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams` + + Body param: Resources (e.g. repositories, files) to mount into the session's container. + +- `--title: optional string` + + Body param: Human-readable session title. + +- `--vault-id: optional array of string` + + Body param: Vault IDs for stored credentials the agent can use during the session. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```cli +ant beta:sessions create \ + --api-key my-anthropic-api-key \ + --agent agent_011CZkYpogX7uDKUyvBTophP \ + --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW +``` diff --git a/content/en/api/cli/beta/sessions/delete.md b/content/en/api/cli/beta/sessions/delete.md new file mode 100644 index 000000000..b08d5960d --- /dev/null +++ b/content/en/api/cli/beta/sessions/delete.md @@ -0,0 +1,37 @@ +## Delete + +`$ ant beta:sessions delete` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_deleted_session: object { id, type }` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Example + +```cli +ant beta:sessions delete \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` diff --git a/content/en/api/cli/beta/sessions/events.md b/content/en/api/cli/beta/sessions/events.md new file mode 100644 index 000000000..6de98f456 --- /dev/null +++ b/content/en/api/cli/beta/sessions/events.md @@ -0,0 +1,9136 @@ +# Events + +## List + +`$ ant beta:sessions:events list` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--limit: optional number` + + Query param: Query parameter for limit + +- `--order: optional "asc" or "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + +- `--page: optional string` + + Query param: Opaque pagination cursor from a previous response's next_page. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListSessionEvents: object { data, next_page }` + + Paginated list of events for a `session`. + + - `data: optional array of BetaManagedAgentsSessionEvent` + + Events for the session, ordered by `created_at`. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:sessions:events list \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Send + +`$ ant beta:sessions:events send` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--event: array of BetaManagedAgentsEventParams` + + Body param: Events to send to the `session`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_send_session_events: object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:events send \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --event "{content: [{text: 'Where is my order #1234?', type: text}], type: user.message}" +``` + +## Stream + +`$ ant beta:sessions:events stream` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_stream_session_events: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```cli +ant beta:sessions:events stream \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Agent Message Event + +- `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Base64 Document Source + +- `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Base64 Image Source + +- `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Billing Error + +- `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + +### Beta Managed Agents Document Block + +- `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + +### Beta Managed Agents Event Params + +- `beta_managed_agents_event_params: BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserInterruptEventParams or BetaManagedAgentsUserToolConfirmationEventParams or BetaManagedAgentsUserCustomToolResultEventParams` + + Union type for event parameters that can be sent to a session. + + - `beta_managed_agents_user_message_event_params: object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `beta_managed_agents_user_interrupt_event_params: object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `beta_managed_agents_user_tool_confirmation_event_params: object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `beta_managed_agents_user_custom_tool_result_event_params: object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents File Image Source + +- `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents Image Block + +- `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Retry Status Exhausted + +- `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + +### Beta Managed Agents Send Session Events + +- `beta_managed_agents_send_session_events: object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + +### Beta Managed Agents Session Error Event + +- `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + +### Beta Managed Agents Session Event + +- `beta_managed_agents_session_event: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Union type for all event types in a session. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `beta_managed_agents_span_model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Stream Session Events + +- `beta_managed_agents_stream_session_events: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Text Block + +- `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Unknown Error + +- `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + +### Beta Managed Agents URL Document Source + +- `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `beta_managed_agents_user_custom_tool_result_event_params: object { custom_tool_use_id, type, content, is_error }` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `beta_managed_agents_user_interrupt_event_params: object { type }` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `beta_managed_agents_user_message_event_params: object { content, type }` + + Parameters for sending a user message to the session. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks for the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `beta_managed_agents_user_tool_confirmation_event_params: object { result, tool_use_id, type, deny_message }` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. diff --git a/content/en/api/cli/beta/sessions/events/list.md b/content/en/api/cli/beta/sessions/events/list.md new file mode 100644 index 000000000..707e40ae1 --- /dev/null +++ b/content/en/api/cli/beta/sessions/events/list.md @@ -0,0 +1,1415 @@ +## List + +`$ ant beta:sessions:events list` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--limit: optional number` + + Query param: Query parameter for limit + +- `--order: optional "asc" or "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + +- `--page: optional string` + + Query param: Opaque pagination cursor from a previous response's next_page. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListSessionEvents: object { data, next_page }` + + Paginated list of events for a `session`. + + - `data: optional array of BetaManagedAgentsSessionEvent` + + Events for the session, ordered by `created_at`. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:sessions:events list \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` diff --git a/content/en/api/cli/beta/sessions/events/send.md b/content/en/api/cli/beta/sessions/events/send.md new file mode 100644 index 000000000..0d29b585e --- /dev/null +++ b/content/en/api/cli/beta/sessions/events/send.md @@ -0,0 +1,420 @@ +## Send + +`$ ant beta:sessions:events send` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--event: array of BetaManagedAgentsEventParams` + + Body param: Events to send to the `session`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_send_session_events: object { data }` + + Events that were successfully sent to the session. + + - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or BetaManagedAgentsUserCustomToolResultEvent` + + Sent events + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:events send \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --event "{content: [{text: 'Where is my order #1234?', type: text}], type: user.message}" +``` diff --git a/content/en/api/cli/beta/sessions/events/stream.md b/content/en/api/cli/beta/sessions/events/stream.md new file mode 100644 index 000000000..69f1ab35a --- /dev/null +++ b/content/en/api/cli/beta/sessions/events/stream.md @@ -0,0 +1,1395 @@ +## Stream + +`$ ant beta:sessions:events stream` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_stream_session_events: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 17 more` + + Server-sent event in the session stream. + + - `beta_managed_agents_user_message_event: object { id, content, type, processed_at }` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + Array of content blocks comprising the user message. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_interrupt_event: object { id, type, processed_at }` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_tool_confirmation_event: object { id, result, tool_use_id, 3 more }` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" or "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message: optional string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_user_custom_tool_result_event: object { id, custom_tool_use_id, type, 3 more }` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `processed_at: optional string` + + A timestamp in RFC 3339 format + + - `beta_managed_agents_agent_custom_tool_use_event: object { id, input, name, 2 more }` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `beta_managed_agents_agent_message_event: object { id, content, processed_at, type }` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: array of BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `beta_managed_agents_agent_thinking_event: object { id, processed_at, type }` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `beta_managed_agents_agent_mcp_tool_use_event: object { id, input, mcp_server_name, 4 more }` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_mcp_tool_result_event: object { id, mcp_tool_use_id, processed_at, 3 more }` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_tool_use_event: object { id, input, name, 3 more }` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: map[unknown]` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission: optional "allow" or "ask" or "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `beta_managed_agents_agent_tool_result_event: object { id, processed_at, tool_use_id, 3 more }` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock` + + The result content returned by the tool. + + - `beta_managed_agents_text_block: object { text, type }` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_image_block: object { source, type }` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `beta_managed_agents_base64_image_source: object { data, media_type, type }` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_url_image_source: object { type, url }` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `beta_managed_agents_file_image_source: object { file_id, type }` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `beta_managed_agents_document_block: object { source, type, context, title }` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `beta_managed_agents_base64_document_source: object { data, media_type, type }` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `beta_managed_agents_plain_text_document_source: object { data, media_type, type }` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `beta_managed_agents_url_document_source: object { type, url }` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `beta_managed_agents_file_document_source: object { file_id, type }` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context: optional string` + + Additional context about the document for the model. + + - `title: optional string` + + The title of the document. + + - `is_error: optional boolean` + + Whether the tool execution resulted in an error. + + - `beta_managed_agents_agent_thread_context_compacted_event: object { id, processed_at, type }` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `beta_managed_agents_session_error_event: object { id, error, processed_at, type }` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `beta_managed_agents_unknown_error: object { message, retry_status, type }` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `beta_managed_agents_model_overloaded_error: object { message, retry_status, type }` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `beta_managed_agents_model_rate_limited_error: object { message, retry_status, type }` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `beta_managed_agents_model_request_failed_error: object { message, retry_status, type }` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `beta_managed_agents_mcp_connection_failed_error: object { mcp_server_name, message, retry_status, type }` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `beta_managed_agents_mcp_authentication_failed_error: object { mcp_server_name, message, retry_status, type }` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `beta_managed_agents_billing_error: object { message, retry_status, type }` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `beta_managed_agents_retry_status_retrying: object { type }` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `beta_managed_agents_retry_status_exhausted: object { type }` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `beta_managed_agents_retry_status_terminal: object { type }` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `beta_managed_agents_session_status_rescheduled_event: object { id, processed_at, type }` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `beta_managed_agents_session_status_running_event: object { id, processed_at, type }` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `beta_managed_agents_session_status_idle_event: object { id, processed_at, stop_reason, type }` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `beta_managed_agents_session_end_turn: object { type }` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `beta_managed_agents_session_requires_action: object { event_ids, type }` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: array of string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `beta_managed_agents_session_retries_exhausted: object { type }` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `beta_managed_agents_session_status_terminated_event: object { id, processed_at, type }` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `beta_managed_agents_span_model_request_start_event: object { id, processed_at, type }` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `beta_managed_agents_span_model_request_end_event: object { id, is_error, model_request_start_id, 3 more }` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `beta_managed_agents_session_deleted_event: object { id, processed_at, type }` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```cli +ant beta:sessions:events stream \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` diff --git a/content/en/api/cli/beta/sessions/list.md b/content/en/api/cli/beta/sessions/list.md new file mode 100644 index 000000000..af60cb225 --- /dev/null +++ b/content/en/api/cli/beta/sessions/list.md @@ -0,0 +1,490 @@ +## List + +`$ ant beta:sessions list` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `--agent-id: optional string` + + Query param: Filter sessions created with this agent ID. + +- `--agent-version: optional number` + + Query param: Filter by agent version. Only applies when agent_id is also set. + +- `--created-at-gt: optional string` + + Query param: Return sessions created after this time (exclusive). + +- `--created-at-gte: optional string` + + Query param: Return sessions created at or after this time (inclusive). + +- `--created-at-lt: optional string` + + Query param: Return sessions created before this time (exclusive). + +- `--created-at-lte: optional string` + + Query param: Return sessions created at or before this time (inclusive). + +- `--include-archived: optional boolean` + + Query param: When true, includes archived sessions. Default: false (exclude archived). + +- `--limit: optional number` + + Query param: Maximum number of results to return. + +- `--order: optional "asc" or "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). + +- `--page: optional string` + + Query param: Opaque pagination cursor from a previous response's next_page. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListSessions: object { data, next_page }` + + Paginated list of sessions. + + - `data: optional array of BetaManagedAgentsSession` + + List of sessions. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:sessions list \ + --api-key my-anthropic-api-key +``` diff --git a/content/en/api/cli/beta/sessions/resources.md b/content/en/api/cli/beta/sessions/resources.md new file mode 100644 index 000000000..327a55b92 --- /dev/null +++ b/content/en/api/cli/beta/sessions/resources.md @@ -0,0 +1,565 @@ +# Resources + +## Add + +`$ ant beta:sessions:resources add` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--file-id: string` + + Body param: ID of a previously uploaded file. + +- `--type: "file"` + + Body param + +- `--mount-path: optional string` + + Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:resources add \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --file-id file_011CNha8iCJcU1wXNR6q4V8w \ + --type file +``` + +## List + +`$ ant beta:sessions:resources list` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--limit: optional number` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `--page: optional string` + + Query param: Opaque cursor from a previous response's next_page field. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListSessionResources: object { data, next_page }` + + Paginated list of resources attached to a session. + + - `data: array of BetaManagedAgentsSessionResource` + + Resources for the session, ordered by `created_at`. + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:sessions:resources list \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` + +## Retrieve + +`$ ant beta:sessions:resources retrieve` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--resource-id: string` + + Path param: Path parameter resource_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSessionResourceGetResponse: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The requested session resource. + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:resources retrieve \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht +``` + +## Update + +`$ ant beta:sessions:resources update` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--resource-id: string` + + Path param: Path parameter resource_id + +- `--authorization-token: string` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSessionResourceUpdateResponse: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The updated session resource. + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:resources update \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht \ + --authorization-token ghp_exampletoken +``` + +## Delete + +`$ ant beta:sessions:resources delete` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--resource-id: string` + + Path param: Path parameter resource_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_delete_session_resource: object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Example + +```cli +ant beta:sessions:resources delete \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `beta_managed_agents_delete_session_resource: object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Session Resource + +- `beta_managed_agents_session_resource: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format diff --git a/content/en/api/cli/beta/sessions/resources/add.md b/content/en/api/cli/beta/sessions/resources/add.md new file mode 100644 index 000000000..b336a49cc --- /dev/null +++ b/content/en/api/cli/beta/sessions/resources/add.md @@ -0,0 +1,61 @@ +## Add + +`$ ant beta:sessions:resources add` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--file-id: string` + + Body param: ID of a previously uploaded file. + +- `--type: "file"` + + Body param + +- `--mount-path: optional string` + + Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:resources add \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --file-id file_011CNha8iCJcU1wXNR6q4V8w \ + --type file +``` diff --git a/content/en/api/cli/beta/sessions/resources/delete.md b/content/en/api/cli/beta/sessions/resources/delete.md new file mode 100644 index 000000000..573243bef --- /dev/null +++ b/content/en/api/cli/beta/sessions/resources/delete.md @@ -0,0 +1,42 @@ +## Delete + +`$ ant beta:sessions:resources delete` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--resource-id: string` + + Path param: Path parameter resource_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_delete_session_resource: object { id, type }` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Example + +```cli +ant beta:sessions:resources delete \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht +``` diff --git a/content/en/api/cli/beta/sessions/resources/list.md b/content/en/api/cli/beta/sessions/resources/list.md new file mode 100644 index 000000000..5fa79caf2 --- /dev/null +++ b/content/en/api/cli/beta/sessions/resources/list.md @@ -0,0 +1,109 @@ +## List + +`$ ant beta:sessions:resources list` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--limit: optional number` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `--page: optional string` + + Query param: Opaque cursor from a previous response's next_page field. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListSessionResources: object { data, next_page }` + + Paginated list of resources attached to a session. + + - `data: array of BetaManagedAgentsSessionResource` + + Resources for the session, ordered by `created_at`. + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `next_page: optional string` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```cli +ant beta:sessions:resources list \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` diff --git a/content/en/api/cli/beta/sessions/resources/retrieve.md b/content/en/api/cli/beta/sessions/resources/retrieve.md new file mode 100644 index 000000000..f92a7736b --- /dev/null +++ b/content/en/api/cli/beta/sessions/resources/retrieve.md @@ -0,0 +1,98 @@ +## Retrieve + +`$ ant beta:sessions:resources retrieve` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--resource-id: string` + + Path param: Path parameter resource_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSessionResourceGetResponse: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The requested session resource. + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:resources retrieve \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht +``` diff --git a/content/en/api/cli/beta/sessions/resources/update.md b/content/en/api/cli/beta/sessions/resources/update.md new file mode 100644 index 000000000..cc0d4f6bb --- /dev/null +++ b/content/en/api/cli/beta/sessions/resources/update.md @@ -0,0 +1,103 @@ +## Update + +`$ ant beta:sessions:resources update` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--resource-id: string` + + Path param: Path parameter resource_id + +- `--authorization-token: string` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSessionResourceUpdateResponse: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource` + + The updated session resource. + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:sessions:resources update \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ + --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht \ + --authorization-token ghp_exampletoken +``` diff --git a/content/en/api/cli/beta/sessions/retrieve.md b/content/en/api/cli/beta/sessions/retrieve.md new file mode 100644 index 000000000..ebe655d94 --- /dev/null +++ b/content/en/api/cli/beta/sessions/retrieve.md @@ -0,0 +1,447 @@ +## Retrieve + +`$ ant beta:sessions retrieve` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `--session-id: string` + + Path parameter session_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```cli +ant beta:sessions retrieve \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` diff --git a/content/en/api/cli/beta/sessions/update.md b/content/en/api/cli/beta/sessions/update.md new file mode 100644 index 000000000..f4f35e99a --- /dev/null +++ b/content/en/api/cli/beta/sessions/update.md @@ -0,0 +1,459 @@ +## Update + +`$ ant beta:sessions update` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `--session-id: string` + + Path param: Path parameter session_id + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + +- `--title: optional string` + + Body param: Human-readable session title. + +- `--vault-id: optional array of string` + + Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_session: object { id, agent, archived_at, 11 more }` + + A Managed Agents `session`. + + - `id: string` + + - `agent: object { id, description, mcp_servers, 7 more }` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string` + + - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: object { id, speed }` + + Model identifier and configuration. + + - `id: "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 5 more or string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `speed: optional "standard" or "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` + + - `beta_managed_agents_anthropic_skill: object { skill_id, type, version }` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `beta_managed_agents_custom_skill: object { skill_id, type, version }` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string` + + - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` + + - `beta_managed_agents_agent_toolset20260401: object { configs, default_config, type }` + + - `configs: array of BetaManagedAgentsAgentToolConfig` + + - `enabled: boolean` + + - `name: "bash" or "edit" or "read" or 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `beta_managed_agents_mcp_toolset: object { configs, default_config, mcp_server_name, type }` + + - `configs: array of BetaManagedAgentsMCPToolConfig` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: object { enabled, permission_policy }` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `beta_managed_agents_always_allow_policy: object { type }` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `beta_managed_agents_always_ask_policy: object { type }` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `beta_managed_agents_custom_tool: object { description, input_schema, name, type }` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: object { properties, required, type }` + + JSON Schema for custom tool input parameters. + + - `properties: optional map[unknown]` + + JSON Schema properties defining the tool's input parameters. + + - `required: optional array of string` + + List of required property names. + + - `type: optional "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: map[string]` + + - `resources: array of BetaManagedAgentsSessionResource` + + - `beta_managed_agents_github_repository_resource: object { id, created_at, mount_path, 4 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` + + - `beta_managed_agents_branch_checkout: object { name, type }` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `beta_managed_agents_commit_checkout: object { sha, type }` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `beta_managed_agents_file_resource: object { id, created_at, file_id, 3 more }` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: object { active_seconds, duration_seconds }` + + Timing statistics for a session. + + - `active_seconds: optional number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: optional number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" or "running" or "idle" or "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }` + + Cumulative token usage for a session across all turns. + + - `cache_creation: optional object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: optional number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: optional number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: optional number` + + Total tokens read from prompt cache. + + - `input_tokens: optional number` + + Total input tokens consumed across all turns. + + - `output_tokens: optional number` + + Total output tokens generated across all turns. + + - `vault_ids: array of string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```cli +ant beta:sessions update \ + --api-key my-anthropic-api-key \ + --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 +``` diff --git a/content/en/api/cli/beta/skills.md b/content/en/api/cli/beta/skills.md index 491f467a9..bcc2f883d 100644 --- a/content/en/api/cli/beta/skills.md +++ b/content/en/api/cli/beta/skills.md @@ -1 +1,615 @@ -Not Found - Claude API Docs
                                            \ No newline at end of file +# Skills + +## Create + +`$ ant beta:skills create` + +**post** `/v1/skills` + +Create Skill + +### Parameters + +- `--display-title: optional string` + + Body param: Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + +- `--file: optional array of string` + + Body param: Files to upload for the skill. + + All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillNewResponse: object { id, created_at, display_title, 4 more }` + + - `id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill was created. + + - `display_title: string` + + Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + + - `latest_version: string` + + The latest version identifier for the skill. + + This represents the most recent version of the skill that has been created. + + - `source: string` + + Source of the skill. + + This may be one of the following values: + + * `"custom"`: the skill was created by a user + * `"anthropic"`: the skill was created by Anthropic + + - `type: string` + + Object type. + + For Skills, this is always `"skill"`. + + - `updated_at: string` + + ISO 8601 timestamp of when the skill was last updated. + +### Example + +```cli +ant beta:skills create \ + --api-key my-anthropic-api-key +``` + +## List + +`$ ant beta:skills list` + +**get** `/v1/skills` + +List Skills + +### Parameters + +- `--limit: optional number` + + Query param: Number of results to return per page. + + Maximum value is 100. Defaults to 20. + +- `--page: optional string` + + Query param: Pagination token for fetching a specific page of results. + + Pass the value from a previous response's `next_page` field to get the next page of results. + +- `--source: optional string` + + Query param: Filter skills by source. + + If provided, only skills from the specified source will be returned: + + * `"custom"`: only return user-created skills + * `"anthropic"`: only return Anthropic-created skills + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListSkillsResponse: object { data, has_more, next_page }` + + - `data: array of object { id, created_at, display_title, 4 more }` + + List of skills. + + - `id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill was created. + + - `display_title: string` + + Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + + - `latest_version: string` + + The latest version identifier for the skill. + + This represents the most recent version of the skill that has been created. + + - `source: string` + + Source of the skill. + + This may be one of the following values: + + * `"custom"`: the skill was created by a user + * `"anthropic"`: the skill was created by Anthropic + + - `type: string` + + Object type. + + For Skills, this is always `"skill"`. + + - `updated_at: string` + + ISO 8601 timestamp of when the skill was last updated. + + - `has_more: boolean` + + Whether there are more results available. + + If `true`, there are additional results that can be fetched using the `next_page` token. + + - `next_page: string` + + Token for fetching the next page of results. + + If `null`, there are no more results available. Pass this value to the `page_token` parameter in the next request to get the next page. + +### Example + +```cli +ant beta:skills list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant beta:skills retrieve` + +**get** `/v1/skills/{skill_id}` + +Get Skill + +### Parameters + +- `--skill-id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillGetResponse: object { id, created_at, display_title, 4 more }` + + - `id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill was created. + + - `display_title: string` + + Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + + - `latest_version: string` + + The latest version identifier for the skill. + + This represents the most recent version of the skill that has been created. + + - `source: string` + + Source of the skill. + + This may be one of the following values: + + * `"custom"`: the skill was created by a user + * `"anthropic"`: the skill was created by Anthropic + + - `type: string` + + Object type. + + For Skills, this is always `"skill"`. + + - `updated_at: string` + + ISO 8601 timestamp of when the skill was last updated. + +### Example + +```cli +ant beta:skills retrieve \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` + +## Delete + +`$ ant beta:skills delete` + +**delete** `/v1/skills/{skill_id}` + +Delete Skill + +### Parameters + +- `--skill-id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillDeleteResponse: object { id, type }` + + - `id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + + - `type: string` + + Deleted object type. + + For Skills, this is always `"skill_deleted"`. + +### Example + +```cli +ant beta:skills delete \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` + +# Versions + +## Create + +`$ ant beta:skills:versions create` + +**post** `/v1/skills/{skill_id}/versions` + +Create Skill Version + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--file: optional array of string` + + Body param: Files to upload for the skill. + + All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillVersionNewResponse: object { id, created_at, description, 5 more }` + + - `id: string` + + Unique identifier for the skill version. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill version was created. + + - `description: string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `directory: string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `name: string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `skill_id: string` + + Identifier for the skill that this version belongs to. + + - `type: string` + + Object type. + + For Skill Versions, this is always `"skill_version"`. + + - `version: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +### Example + +```cli +ant beta:skills:versions create \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` + +## List + +`$ ant beta:skills:versions list` + +**get** `/v1/skills/{skill_id}/versions` + +List Skill Versions + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--page: optional string` + + Query param: Optionally set to the `next_page` token from the previous response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListSkillVersionsResponse: object { data, has_more, next_page }` + + - `data: array of object { id, created_at, description, 5 more }` + + List of skill versions. + + - `id: string` + + Unique identifier for the skill version. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill version was created. + + - `description: string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `directory: string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `name: string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `skill_id: string` + + Identifier for the skill that this version belongs to. + + - `type: string` + + Object type. + + For Skill Versions, this is always `"skill_version"`. + + - `version: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `next_page: string` + + Token to provide in as `page` in the subsequent request to retrieve the next page of data. + +### Example + +```cli +ant beta:skills:versions list \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` + +## Retrieve + +`$ ant beta:skills:versions retrieve` + +**get** `/v1/skills/{skill_id}/versions/{version}` + +Get Skill Version + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--version: string` + + Path param: Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillVersionGetResponse: object { id, created_at, description, 5 more }` + + - `id: string` + + Unique identifier for the skill version. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill version was created. + + - `description: string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `directory: string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `name: string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `skill_id: string` + + Identifier for the skill that this version belongs to. + + - `type: string` + + Object type. + + For Skill Versions, this is always `"skill_version"`. + + - `version: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +### Example + +```cli +ant beta:skills:versions retrieve \ + --api-key my-anthropic-api-key \ + --skill-id skill_id \ + --version version +``` + +## Delete + +`$ ant beta:skills:versions delete` + +**delete** `/v1/skills/{skill_id}/versions/{version}` + +Delete Skill Version + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--version: string` + + Path param: Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillVersionDeleteResponse: object { id, type }` + + - `id: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + + - `type: string` + + Deleted object type. + + For Skill Versions, this is always `"skill_version_deleted"`. + +### Example + +```cli +ant beta:skills:versions delete \ + --api-key my-anthropic-api-key \ + --skill-id skill_id \ + --version version +``` diff --git a/content/en/api/cli/beta/skills/create.md b/content/en/api/cli/beta/skills/create.md index 8f399abd2..2b99864c8 100644 --- a/content/en/api/cli/beta/skills/create.md +++ b/content/en/api/cli/beta/skills/create.md @@ -1 +1,77 @@ -Not Found - Claude API Docs
                                              \ No newline at end of file +## Create + +`$ ant beta:skills create` + +**post** `/v1/skills` + +Create Skill + +### Parameters + +- `--display-title: optional string` + + Body param: Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + +- `--file: optional array of string` + + Body param: Files to upload for the skill. + + All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillNewResponse: object { id, created_at, display_title, 4 more }` + + - `id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill was created. + + - `display_title: string` + + Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + + - `latest_version: string` + + The latest version identifier for the skill. + + This represents the most recent version of the skill that has been created. + + - `source: string` + + Source of the skill. + + This may be one of the following values: + + * `"custom"`: the skill was created by a user + * `"anthropic"`: the skill was created by Anthropic + + - `type: string` + + Object type. + + For Skills, this is always `"skill"`. + + - `updated_at: string` + + ISO 8601 timestamp of when the skill was last updated. + +### Example + +```cli +ant beta:skills create \ + --api-key my-anthropic-api-key +``` diff --git a/content/en/api/cli/beta/skills/delete.md b/content/en/api/cli/beta/skills/delete.md index 9327077a9..29ebac763 100644 --- a/content/en/api/cli/beta/skills/delete.md +++ b/content/en/api/cli/beta/skills/delete.md @@ -1 +1,43 @@ -Not Found - Claude API Docs
                                                \ No newline at end of file +## Delete + +`$ ant beta:skills delete` + +**delete** `/v1/skills/{skill_id}` + +Delete Skill + +### Parameters + +- `--skill-id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillDeleteResponse: object { id, type }` + + - `id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + + - `type: string` + + Deleted object type. + + For Skills, this is always `"skill_deleted"`. + +### Example + +```cli +ant beta:skills delete \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` diff --git a/content/en/api/cli/beta/skills/list.md b/content/en/api/cli/beta/skills/list.md index 88c4e9be4..2e59ace31 100644 --- a/content/en/api/cli/beta/skills/list.md +++ b/content/en/api/cli/beta/skills/list.md @@ -1 +1,102 @@ -Not Found - Claude API Docs
                                                  \ No newline at end of file +## List + +`$ ant beta:skills list` + +**get** `/v1/skills` + +List Skills + +### Parameters + +- `--limit: optional number` + + Query param: Number of results to return per page. + + Maximum value is 100. Defaults to 20. + +- `--page: optional string` + + Query param: Pagination token for fetching a specific page of results. + + Pass the value from a previous response's `next_page` field to get the next page of results. + +- `--source: optional string` + + Query param: Filter skills by source. + + If provided, only skills from the specified source will be returned: + + * `"custom"`: only return user-created skills + * `"anthropic"`: only return Anthropic-created skills + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListSkillsResponse: object { data, has_more, next_page }` + + - `data: array of object { id, created_at, display_title, 4 more }` + + List of skills. + + - `id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill was created. + + - `display_title: string` + + Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + + - `latest_version: string` + + The latest version identifier for the skill. + + This represents the most recent version of the skill that has been created. + + - `source: string` + + Source of the skill. + + This may be one of the following values: + + * `"custom"`: the skill was created by a user + * `"anthropic"`: the skill was created by Anthropic + + - `type: string` + + Object type. + + For Skills, this is always `"skill"`. + + - `updated_at: string` + + ISO 8601 timestamp of when the skill was last updated. + + - `has_more: boolean` + + Whether there are more results available. + + If `true`, there are additional results that can be fetched using the `next_page` token. + + - `next_page: string` + + Token for fetching the next page of results. + + If `null`, there are no more results available. Pass this value to the `page_token` parameter in the next request to get the next page. + +### Example + +```cli +ant beta:skills list \ + --api-key my-anthropic-api-key +``` diff --git a/content/en/api/cli/beta/skills/retrieve.md b/content/en/api/cli/beta/skills/retrieve.md index c74c3e785..bc965afd1 100644 --- a/content/en/api/cli/beta/skills/retrieve.md +++ b/content/en/api/cli/beta/skills/retrieve.md @@ -1 +1,72 @@ -Not Found - Claude API Docs
                                                    \ No newline at end of file +## Retrieve + +`$ ant beta:skills retrieve` + +**get** `/v1/skills/{skill_id}` + +Get Skill + +### Parameters + +- `--skill-id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillGetResponse: object { id, created_at, display_title, 4 more }` + + - `id: string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill was created. + + - `display_title: string` + + Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + + - `latest_version: string` + + The latest version identifier for the skill. + + This represents the most recent version of the skill that has been created. + + - `source: string` + + Source of the skill. + + This may be one of the following values: + + * `"custom"`: the skill was created by a user + * `"anthropic"`: the skill was created by Anthropic + + - `type: string` + + Object type. + + For Skills, this is always `"skill"`. + + - `updated_at: string` + + ISO 8601 timestamp of when the skill was last updated. + +### Example + +```cli +ant beta:skills retrieve \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` diff --git a/content/en/api/cli/beta/skills/versions.md b/content/en/api/cli/beta/skills/versions.md index 816fde711..847ca95c1 100644 --- a/content/en/api/cli/beta/skills/versions.md +++ b/content/en/api/cli/beta/skills/versions.md @@ -1 +1,315 @@ -Not Found - Claude API Docs
                                                      \ No newline at end of file +# Versions + +## Create + +`$ ant beta:skills:versions create` + +**post** `/v1/skills/{skill_id}/versions` + +Create Skill Version + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--file: optional array of string` + + Body param: Files to upload for the skill. + + All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillVersionNewResponse: object { id, created_at, description, 5 more }` + + - `id: string` + + Unique identifier for the skill version. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill version was created. + + - `description: string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `directory: string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `name: string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `skill_id: string` + + Identifier for the skill that this version belongs to. + + - `type: string` + + Object type. + + For Skill Versions, this is always `"skill_version"`. + + - `version: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +### Example + +```cli +ant beta:skills:versions create \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` + +## List + +`$ ant beta:skills:versions list` + +**get** `/v1/skills/{skill_id}/versions` + +List Skill Versions + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--page: optional string` + + Query param: Optionally set to the `next_page` token from the previous response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListSkillVersionsResponse: object { data, has_more, next_page }` + + - `data: array of object { id, created_at, description, 5 more }` + + List of skill versions. + + - `id: string` + + Unique identifier for the skill version. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill version was created. + + - `description: string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `directory: string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `name: string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `skill_id: string` + + Identifier for the skill that this version belongs to. + + - `type: string` + + Object type. + + For Skill Versions, this is always `"skill_version"`. + + - `version: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `next_page: string` + + Token to provide in as `page` in the subsequent request to retrieve the next page of data. + +### Example + +```cli +ant beta:skills:versions list \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` + +## Retrieve + +`$ ant beta:skills:versions retrieve` + +**get** `/v1/skills/{skill_id}/versions/{version}` + +Get Skill Version + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--version: string` + + Path param: Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillVersionGetResponse: object { id, created_at, description, 5 more }` + + - `id: string` + + Unique identifier for the skill version. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill version was created. + + - `description: string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `directory: string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `name: string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `skill_id: string` + + Identifier for the skill that this version belongs to. + + - `type: string` + + Object type. + + For Skill Versions, this is always `"skill_version"`. + + - `version: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +### Example + +```cli +ant beta:skills:versions retrieve \ + --api-key my-anthropic-api-key \ + --skill-id skill_id \ + --version version +``` + +## Delete + +`$ ant beta:skills:versions delete` + +**delete** `/v1/skills/{skill_id}/versions/{version}` + +Delete Skill Version + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--version: string` + + Path param: Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillVersionDeleteResponse: object { id, type }` + + - `id: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + + - `type: string` + + Deleted object type. + + For Skill Versions, this is always `"skill_version_deleted"`. + +### Example + +```cli +ant beta:skills:versions delete \ + --api-key my-anthropic-api-key \ + --skill-id skill_id \ + --version version +``` diff --git a/content/en/api/cli/beta/skills/versions/create.md b/content/en/api/cli/beta/skills/versions/create.md index 6c7c84078..ff6e0d825 100644 --- a/content/en/api/cli/beta/skills/versions/create.md +++ b/content/en/api/cli/beta/skills/versions/create.md @@ -1 +1,81 @@ -Not Found - Claude API Docs
                                                        \ No newline at end of file +## Create + +`$ ant beta:skills:versions create` + +**post** `/v1/skills/{skill_id}/versions` + +Create Skill Version + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--file: optional array of string` + + Body param: Files to upload for the skill. + + All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillVersionNewResponse: object { id, created_at, description, 5 more }` + + - `id: string` + + Unique identifier for the skill version. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill version was created. + + - `description: string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `directory: string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `name: string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `skill_id: string` + + Identifier for the skill that this version belongs to. + + - `type: string` + + Object type. + + For Skill Versions, this is always `"skill_version"`. + + - `version: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +### Example + +```cli +ant beta:skills:versions create \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` diff --git a/content/en/api/cli/beta/skills/versions/delete.md b/content/en/api/cli/beta/skills/versions/delete.md index 1026c1b06..44eca6ac9 100644 --- a/content/en/api/cli/beta/skills/versions/delete.md +++ b/content/en/api/cli/beta/skills/versions/delete.md @@ -1 +1,50 @@ -Not Found - Claude API Docs
                                                          \ No newline at end of file +## Delete + +`$ ant beta:skills:versions delete` + +**delete** `/v1/skills/{skill_id}/versions/{version}` + +Delete Skill Version + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--version: string` + + Path param: Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillVersionDeleteResponse: object { id, type }` + + - `id: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + + - `type: string` + + Deleted object type. + + For Skill Versions, this is always `"skill_version_deleted"`. + +### Example + +```cli +ant beta:skills:versions delete \ + --api-key my-anthropic-api-key \ + --skill-id skill_id \ + --version version +``` diff --git a/content/en/api/cli/beta/skills/versions/list.md b/content/en/api/cli/beta/skills/versions/list.md index 1ddd29677..0a3f78020 100644 --- a/content/en/api/cli/beta/skills/versions/list.md +++ b/content/en/api/cli/beta/skills/versions/list.md @@ -1 +1,97 @@ -Not Found - Claude API Docs
                                                            \ No newline at end of file +## List + +`$ ant beta:skills:versions list` + +**get** `/v1/skills/{skill_id}/versions` + +List Skill Versions + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--page: optional string` + + Query param: Optionally set to the `next_page` token from the previous response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaListSkillVersionsResponse: object { data, has_more, next_page }` + + - `data: array of object { id, created_at, description, 5 more }` + + List of skill versions. + + - `id: string` + + Unique identifier for the skill version. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill version was created. + + - `description: string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `directory: string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `name: string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `skill_id: string` + + Identifier for the skill that this version belongs to. + + - `type: string` + + Object type. + + For Skill Versions, this is always `"skill_version"`. + + - `version: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `next_page: string` + + Token to provide in as `page` in the subsequent request to retrieve the next page of data. + +### Example + +```cli +ant beta:skills:versions list \ + --api-key my-anthropic-api-key \ + --skill-id skill_id +``` diff --git a/content/en/api/cli/beta/skills/versions/retrieve.md b/content/en/api/cli/beta/skills/versions/retrieve.md index 17cfea617..e1b5fd434 100644 --- a/content/en/api/cli/beta/skills/versions/retrieve.md +++ b/content/en/api/cli/beta/skills/versions/retrieve.md @@ -1 +1,82 @@ -Not Found - Claude API Docs
                                                              \ No newline at end of file +## Retrieve + +`$ ant beta:skills:versions retrieve` + +**get** `/v1/skills/{skill_id}/versions/{version}` + +Get Skill Version + +### Parameters + +- `--skill-id: string` + + Path param: Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `--version: string` + + Path param: Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaSkillVersionGetResponse: object { id, created_at, description, 5 more }` + + - `id: string` + + Unique identifier for the skill version. + + The format and length of IDs may change over time. + + - `created_at: string` + + ISO 8601 timestamp of when the skill version was created. + + - `description: string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `directory: string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `name: string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `skill_id: string` + + Identifier for the skill that this version belongs to. + + - `type: string` + + Object type. + + For Skill Versions, this is always `"skill_version"`. + + - `version: string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +### Example + +```cli +ant beta:skills:versions retrieve \ + --api-key my-anthropic-api-key \ + --skill-id skill_id \ + --version version +``` diff --git a/content/en/api/cli/beta/vaults.md b/content/en/api/cli/beta/vaults.md new file mode 100644 index 000000000..c82e18caa --- /dev/null +++ b/content/en/api/cli/beta/vaults.md @@ -0,0 +1,1881 @@ +# Vaults + +## Create + +`$ ant beta:vaults create` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `--display-name: string` + + Body param: Human-readable name for the vault. 1-255 characters. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata to attach to the vault. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:vaults create \ + --api-key my-anthropic-api-key \ + --display-name 'Example vault' +``` + +## List + +`$ ant beta:vaults list` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `--include-archived: optional boolean` + + Query param: Whether to include archived vaults in the results. + +- `--limit: optional number` + + Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination token from a previous `list_vaults` response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListVaultsResponse: object { data, next_page }` + + Response containing a paginated list of vaults. + + - `data: optional array of BetaManagedAgentsVault` + + List of vaults. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```cli +ant beta:vaults list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant beta:vaults retrieve` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `--vault-id: string` + + Path parameter vault_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:vaults retrieve \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` + +## Update + +`$ ant beta:vaults update` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--display-name: optional string` + + Body param: Updated human-readable name for the vault. 1-255 characters. + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:vaults update \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` + +## Delete + +`$ ant beta:vaults delete` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `--vault-id: string` + + Path parameter vault_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_deleted_vault: object { id, type }` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Example + +```cli +ant beta:vaults delete \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` + +## Archive + +`$ ant beta:vaults archive` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `--vault-id: string` + + Path parameter vault_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:vaults archive \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `beta_managed_agents_deleted_vault: object { id, type }` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Beta Managed Agents Vault + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`$ ant beta:vaults:credentials create` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--auth: BetaManagedAgentsMCPOAuthCreateParams or BetaManagedAgentsStaticBearerCreateParams` + + Body param: Authentication details for creating a credential. + +- `--display-name: optional string` + + Body param: Human-readable name for the credential. Up to 255 characters. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata to attach to the credential. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials create \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --auth '{token: bearer_exampletoken, mcp_server_url: https://example-server.modelcontextprotocol.io/sse, type: static_bearer}' +``` + +## List + +`$ ant beta:vaults:credentials list` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--include-archived: optional boolean` + + Query param: Whether to include archived credentials in the results. + +- `--limit: optional number` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination token from a previous `list_credentials` response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListCredentialsResponse: object { data, next_page }` + + Response containing a paginated list of credentials. + + - `data: optional array of BetaManagedAgentsCredential` + + List of credentials. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + + - `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```cli +ant beta:vaults:credentials list \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` + +## Retrieve + +`$ ant beta:vaults:credentials retrieve` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials retrieve \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` + +## Update + +`$ ant beta:vaults:credentials update` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--auth: optional BetaManagedAgentsMCPOAuthUpdateParams or BetaManagedAgentsStaticBearerUpdateParams` + + Body param: Updated authentication details for a credential. + +- `--display-name: optional string` + + Body param: Updated human-readable name for the credential. 1-255 characters. + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials update \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` + +## Delete + +`$ ant beta:vaults:credentials delete` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_deleted_credential: object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Example + +```cli +ant beta:vaults:credentials delete \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` + +## Archive + +`$ ant beta:vaults:credentials archive` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials archive \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `beta_managed_agents_deleted_credential: object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `beta_managed_agents_mcp_oauth_create_params: object { access_token, mcp_server_url, type, 2 more }` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, refresh_token, token_endpoint, 3 more }` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_param: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_param: object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_param: object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `beta_managed_agents_mcp_oauth_refresh_params: object { client_id, refresh_token, token_endpoint, 3 more }` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_param: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_param: object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_param: object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `beta_managed_agents_mcp_oauth_refresh_response: object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `beta_managed_agents_mcp_oauth_refresh_update_params: object { refresh_token, scope, token_endpoint_auth }` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `beta_managed_agents_token_endpoint_auth_basic_update_param: object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `beta_managed_agents_token_endpoint_auth_post_update_param: object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `beta_managed_agents_mcp_oauth_update_params: object { type, access_token, expires_at, refresh }` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token: optional string` + + Updated OAuth access token. + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { refresh_token, scope, token_endpoint_auth }` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `beta_managed_agents_token_endpoint_auth_basic_update_param: object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `beta_managed_agents_token_endpoint_auth_post_update_param: object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `beta_managed_agents_static_bearer_create_params: object { token, mcp_server_url, type }` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `beta_managed_agents_static_bearer_update_params: object { type, token }` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token: optional string` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `beta_managed_agents_token_endpoint_auth_basic_param: object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `beta_managed_agents_token_endpoint_auth_basic_update_param: object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `beta_managed_agents_token_endpoint_auth_none_param: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `beta_managed_agents_token_endpoint_auth_post_param: object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `beta_managed_agents_token_endpoint_auth_post_update_param: object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. diff --git a/content/en/api/cli/beta/vaults/archive.md b/content/en/api/cli/beta/vaults/archive.md new file mode 100644 index 000000000..daf03c8dd --- /dev/null +++ b/content/en/api/cli/beta/vaults/archive.md @@ -0,0 +1,59 @@ +## Archive + +`$ ant beta:vaults archive` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `--vault-id: string` + + Path parameter vault_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:vaults archive \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` diff --git a/content/en/api/cli/beta/vaults/create.md b/content/en/api/cli/beta/vaults/create.md new file mode 100644 index 000000000..0ee8653ee --- /dev/null +++ b/content/en/api/cli/beta/vaults/create.md @@ -0,0 +1,63 @@ +## Create + +`$ ant beta:vaults create` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `--display-name: string` + + Body param: Human-readable name for the vault. 1-255 characters. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata to attach to the vault. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:vaults create \ + --api-key my-anthropic-api-key \ + --display-name 'Example vault' +``` diff --git a/content/en/api/cli/beta/vaults/credentials.md b/content/en/api/cli/beta/vaults/credentials.md new file mode 100644 index 000000000..50fe62a80 --- /dev/null +++ b/content/en/api/cli/beta/vaults/credentials.md @@ -0,0 +1,1462 @@ +# Credentials + +## Create + +`$ ant beta:vaults:credentials create` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--auth: BetaManagedAgentsMCPOAuthCreateParams or BetaManagedAgentsStaticBearerCreateParams` + + Body param: Authentication details for creating a credential. + +- `--display-name: optional string` + + Body param: Human-readable name for the credential. Up to 255 characters. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata to attach to the credential. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials create \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --auth '{token: bearer_exampletoken, mcp_server_url: https://example-server.modelcontextprotocol.io/sse, type: static_bearer}' +``` + +## List + +`$ ant beta:vaults:credentials list` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--include-archived: optional boolean` + + Query param: Whether to include archived credentials in the results. + +- `--limit: optional number` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination token from a previous `list_credentials` response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListCredentialsResponse: object { data, next_page }` + + Response containing a paginated list of credentials. + + - `data: optional array of BetaManagedAgentsCredential` + + List of credentials. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + + - `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```cli +ant beta:vaults:credentials list \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` + +## Retrieve + +`$ ant beta:vaults:credentials retrieve` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials retrieve \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` + +## Update + +`$ ant beta:vaults:credentials update` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--auth: optional BetaManagedAgentsMCPOAuthUpdateParams or BetaManagedAgentsStaticBearerUpdateParams` + + Body param: Updated authentication details for a credential. + +- `--display-name: optional string` + + Body param: Updated human-readable name for the credential. 1-255 characters. + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials update \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` + +## Delete + +`$ ant beta:vaults:credentials delete` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_deleted_credential: object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Example + +```cli +ant beta:vaults:credentials delete \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` + +## Archive + +`$ ant beta:vaults:credentials archive` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials archive \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `beta_managed_agents_deleted_credential: object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `beta_managed_agents_mcp_oauth_create_params: object { access_token, mcp_server_url, type, 2 more }` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, refresh_token, token_endpoint, 3 more }` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_param: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_param: object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_param: object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `beta_managed_agents_mcp_oauth_refresh_params: object { client_id, refresh_token, token_endpoint, 3 more }` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_param: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_param: object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_param: object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `beta_managed_agents_mcp_oauth_refresh_response: object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `beta_managed_agents_mcp_oauth_refresh_update_params: object { refresh_token, scope, token_endpoint_auth }` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `beta_managed_agents_token_endpoint_auth_basic_update_param: object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `beta_managed_agents_token_endpoint_auth_post_update_param: object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `beta_managed_agents_mcp_oauth_update_params: object { type, access_token, expires_at, refresh }` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token: optional string` + + Updated OAuth access token. + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { refresh_token, scope, token_endpoint_auth }` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: optional string` + + Updated OAuth refresh token. + + - `scope: optional string` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `beta_managed_agents_token_endpoint_auth_basic_update_param: object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + + - `beta_managed_agents_token_endpoint_auth_post_update_param: object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `beta_managed_agents_static_bearer_create_params: object { token, mcp_server_url, type }` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `beta_managed_agents_static_bearer_update_params: object { type, token }` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token: optional string` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `beta_managed_agents_token_endpoint_auth_basic_param: object { client_secret, type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `beta_managed_agents_token_endpoint_auth_basic_update_param: object { type, client_secret }` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret: optional string` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `beta_managed_agents_token_endpoint_auth_none_param: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `beta_managed_agents_token_endpoint_auth_post_param: object { client_secret, type }` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `beta_managed_agents_token_endpoint_auth_post_update_param: object { type, client_secret }` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret: optional string` + + Updated OAuth client secret. diff --git a/content/en/api/cli/beta/vaults/credentials/archive.md b/content/en/api/cli/beta/vaults/credentials/archive.md new file mode 100644 index 000000000..11bde71ac --- /dev/null +++ b/content/en/api/cli/beta/vaults/credentials/archive.md @@ -0,0 +1,148 @@ +## Archive + +`$ ant beta:vaults:credentials archive` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials archive \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` diff --git a/content/en/api/cli/beta/vaults/credentials/create.md b/content/en/api/cli/beta/vaults/credentials/create.md new file mode 100644 index 000000000..b292b4577 --- /dev/null +++ b/content/en/api/cli/beta/vaults/credentials/create.md @@ -0,0 +1,156 @@ +## Create + +`$ ant beta:vaults:credentials create` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--auth: BetaManagedAgentsMCPOAuthCreateParams or BetaManagedAgentsStaticBearerCreateParams` + + Body param: Authentication details for creating a credential. + +- `--display-name: optional string` + + Body param: Human-readable name for the credential. Up to 255 characters. + +- `--metadata: optional map[string]` + + Body param: Arbitrary key-value metadata to attach to the credential. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials create \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --auth '{token: bearer_exampletoken, mcp_server_url: https://example-server.modelcontextprotocol.io/sse, type: static_bearer}' +``` diff --git a/content/en/api/cli/beta/vaults/credentials/delete.md b/content/en/api/cli/beta/vaults/credentials/delete.md new file mode 100644 index 000000000..f98f8bb0b --- /dev/null +++ b/content/en/api/cli/beta/vaults/credentials/delete.md @@ -0,0 +1,44 @@ +## Delete + +`$ ant beta:vaults:credentials delete` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_deleted_credential: object { id, type }` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Example + +```cli +ant beta:vaults:credentials delete \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` diff --git a/content/en/api/cli/beta/vaults/credentials/list.md b/content/en/api/cli/beta/vaults/credentials/list.md new file mode 100644 index 000000000..b7b10167e --- /dev/null +++ b/content/en/api/cli/beta/vaults/credentials/list.md @@ -0,0 +1,163 @@ +## List + +`$ ant beta:vaults:credentials list` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--include-archived: optional boolean` + + Query param: Whether to include archived credentials in the results. + +- `--limit: optional number` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination token from a previous `list_credentials` response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListCredentialsResponse: object { data, next_page }` + + Response containing a paginated list of credentials. + + - `data: optional array of BetaManagedAgentsCredential` + + List of credentials. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + + - `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```cli +ant beta:vaults:credentials list \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` diff --git a/content/en/api/cli/beta/vaults/credentials/retrieve.md b/content/en/api/cli/beta/vaults/credentials/retrieve.md new file mode 100644 index 000000000..f28ca9bc6 --- /dev/null +++ b/content/en/api/cli/beta/vaults/credentials/retrieve.md @@ -0,0 +1,148 @@ +## Retrieve + +`$ ant beta:vaults:credentials retrieve` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials retrieve \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` diff --git a/content/en/api/cli/beta/vaults/credentials/update.md b/content/en/api/cli/beta/vaults/credentials/update.md new file mode 100644 index 000000000..2e22a76dd --- /dev/null +++ b/content/en/api/cli/beta/vaults/credentials/update.md @@ -0,0 +1,160 @@ +## Update + +`$ ant beta:vaults:credentials update` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--credential-id: string` + + Path param: Path parameter credential_id + +- `--auth: optional BetaManagedAgentsMCPOAuthUpdateParams or BetaManagedAgentsStaticBearerUpdateParams` + + Body param: Updated authentication details for a credential. + +- `--display-name: optional string` + + Body param: Updated human-readable name for the credential. 1-255 characters. + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_credential: object { id, archived_at, auth, 6 more }` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `beta_managed_agents_mcp_oauth_auth_response: object { mcp_server_url, type, expires_at, refresh }` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at: optional string` + + A timestamp in RFC 3339 format + + - `refresh: optional object { client_id, token_endpoint, token_endpoint_auth, 2 more }` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `beta_managed_agents_token_endpoint_auth_none_response: object { type }` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `beta_managed_agents_token_endpoint_auth_basic_response: object { type }` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `beta_managed_agents_token_endpoint_auth_post_response: object { type }` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource: optional string` + + OAuth resource indicator. + + - `scope: optional string` + + OAuth scope for the refresh request. + + - `beta_managed_agents_static_bearer_auth_response: object { mcp_server_url, type }` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name: optional string` + + Human-readable name for the credential. + +### Example + +```cli +ant beta:vaults:credentials update \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ + --credential-id vcrd_011CZkZEMt8gZan2iYOQfSkw +``` diff --git a/content/en/api/cli/beta/vaults/delete.md b/content/en/api/cli/beta/vaults/delete.md new file mode 100644 index 000000000..3ccc04b4a --- /dev/null +++ b/content/en/api/cli/beta/vaults/delete.md @@ -0,0 +1,39 @@ +## Delete + +`$ ant beta:vaults delete` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `--vault-id: string` + + Path parameter vault_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_deleted_vault: object { id, type }` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Example + +```cli +ant beta:vaults delete \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` diff --git a/content/en/api/cli/beta/vaults/list.md b/content/en/api/cli/beta/vaults/list.md new file mode 100644 index 000000000..2792e12fb --- /dev/null +++ b/content/en/api/cli/beta/vaults/list.md @@ -0,0 +1,74 @@ +## List + +`$ ant beta:vaults list` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `--include-archived: optional boolean` + + Query param: Whether to include archived vaults in the results. + +- `--limit: optional number` + + Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. + +- `--page: optional string` + + Query param: Opaque pagination token from a previous `list_vaults` response. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `BetaManagedAgentsListVaultsResponse: object { data, next_page }` + + Response containing a paginated list of vaults. + + - `data: optional array of BetaManagedAgentsVault` + + List of vaults. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `next_page: optional string` + + Pagination token for the next page, or null if no more results. + +### Example + +```cli +ant beta:vaults list \ + --api-key my-anthropic-api-key +``` diff --git a/content/en/api/cli/beta/vaults/retrieve.md b/content/en/api/cli/beta/vaults/retrieve.md new file mode 100644 index 000000000..e2251a13d --- /dev/null +++ b/content/en/api/cli/beta/vaults/retrieve.md @@ -0,0 +1,59 @@ +## Retrieve + +`$ ant beta:vaults retrieve` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `--vault-id: string` + + Path parameter vault_id + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:vaults retrieve \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` diff --git a/content/en/api/cli/beta/vaults/update.md b/content/en/api/cli/beta/vaults/update.md new file mode 100644 index 000000000..07c37540d --- /dev/null +++ b/content/en/api/cli/beta/vaults/update.md @@ -0,0 +1,67 @@ +## Update + +`$ ant beta:vaults update` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `--vault-id: string` + + Path param: Path parameter vault_id + +- `--display-name: optional string` + + Body param: Updated human-readable name for the vault. 1-255 characters. + +- `--metadata: optional map[string]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `beta_managed_agents_vault: object { id, archived_at, created_at, 4 more }` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: map[string]` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```cli +ant beta:vaults update \ + --api-key my-anthropic-api-key \ + --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv +``` diff --git a/content/en/api/cli/completions.md b/content/en/api/cli/completions.md index 98235cd3c..e2d7563a2 100644 --- a/content/en/api/cli/completions.md +++ b/content/en/api/cli/completions.md @@ -1 +1,301 @@ -Not Found - Claude API Docs
                                                                \ No newline at end of file +# Completions + +## Create + +`$ ant completions create` + +**post** `/v1/complete` + +[Legacy] Create a Text Completion. + +The Text Completions API is a legacy API. We recommend using the [Messages API](https://docs.claude.com/en/api/messages) going forward. + +Future models and features will not be compatible with Text Completions. See our [migration guide](https://docs.claude.com/en/api/migrating-from-text-completions-to-messages) for guidance in migrating from Text Completions to Messages. + +### Parameters + +- `--max-tokens-to-sample: number` + + Body param: The maximum number of tokens to generate before stopping. + + Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. + +- `--model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + Body param: The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--prompt: string` + + Body param: The prompt that you want Claude to complete. + + For proper response generation you will need to format your prompt using alternating ` + + Human:`and` + + Assistant:` conversational turns. For example: + + ``` + " + + Human: {userQuestion} + + Assistant:" + ``` + + See [prompt validation](https://docs.claude.com/en/api/prompt-validation) and our guide to [prompt design](https://docs.claude.com/en/docs/intro-to-prompting) for more details. + +- `--metadata: optional object { user_id }` + + Body param: An object describing metadata about the request. + +- `--stop-sequence: optional array of string` + + Body param: Sequences that will cause the model to stop generating. + + Our models stop on `" + + Human:"`, and may include additional built-in stop sequences in the future. By providing the stop_sequences parameter, you may include additional strings that will cause the model to stop generating. + +- `--temperature: optional number` + + Body param: Amount of randomness injected into the response. + + Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. + + Note that even with `temperature` of `0.0`, the results will not be fully deterministic. + +- `--top-k: optional number` + + Body param: Only sample from the top K options for each subsequent token. + + Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--top-p: optional number` + + Body param: Use nucleus sampling. + + In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `completion: object { id, completion, model, 2 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `completion: string` + + The resulting completion up to and excluding the stop sequences. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `stop_reason: string` + + The reason that we stopped. + + This may be one the following values: + + * `"stop_sequence"`: we reached a stop sequence — either provided by you via the `stop_sequences` parameter, or a stop sequence built into the model + * `"max_tokens"`: we exceeded `max_tokens_to_sample` or the model's maximum + + - `type: "completion"` + + Object type. + + For Text Completions, this is always `"completion"`. + +### Example + +```cli +ant completions create \ + --api-key my-anthropic-api-key \ + --max-tokens-to-sample 256 \ + --model claude-mythos-preview \ + --prompt ' + +Human: Hello, world! + +Assistant:' +``` + +## Domain Types + +### Completion + +- `completion: object { id, completion, model, 2 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `completion: string` + + The resulting completion up to and excluding the stop sequences. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `stop_reason: string` + + The reason that we stopped. + + This may be one the following values: + + * `"stop_sequence"`: we reached a stop sequence — either provided by you via the `stop_sequences` parameter, or a stop sequence built into the model + * `"max_tokens"`: we exceeded `max_tokens_to_sample` or the model's maximum + + - `type: "completion"` + + Object type. + + For Text Completions, this is always `"completion"`. diff --git a/content/en/api/cli/completions/create.md b/content/en/api/cli/completions/create.md index eb0377b2c..85134903b 100644 --- a/content/en/api/cli/completions/create.md +++ b/content/en/api/cli/completions/create.md @@ -1 +1,198 @@ -Not Found - Claude API Docs
                                                                  \ No newline at end of file +## Create + +`$ ant completions create` + +**post** `/v1/complete` + +[Legacy] Create a Text Completion. + +The Text Completions API is a legacy API. We recommend using the [Messages API](https://docs.claude.com/en/api/messages) going forward. + +Future models and features will not be compatible with Text Completions. See our [migration guide](https://docs.claude.com/en/api/migrating-from-text-completions-to-messages) for guidance in migrating from Text Completions to Messages. + +### Parameters + +- `--max-tokens-to-sample: number` + + Body param: The maximum number of tokens to generate before stopping. + + Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. + +- `--model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + Body param: The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--prompt: string` + + Body param: The prompt that you want Claude to complete. + + For proper response generation you will need to format your prompt using alternating ` + + Human:`and` + + Assistant:` conversational turns. For example: + + ``` + " + + Human: {userQuestion} + + Assistant:" + ``` + + See [prompt validation](https://docs.claude.com/en/api/prompt-validation) and our guide to [prompt design](https://docs.claude.com/en/docs/intro-to-prompting) for more details. + +- `--metadata: optional object { user_id }` + + Body param: An object describing metadata about the request. + +- `--stop-sequence: optional array of string` + + Body param: Sequences that will cause the model to stop generating. + + Our models stop on `" + + Human:"`, and may include additional built-in stop sequences in the future. By providing the stop_sequences parameter, you may include additional strings that will cause the model to stop generating. + +- `--temperature: optional number` + + Body param: Amount of randomness injected into the response. + + Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. + + Note that even with `temperature` of `0.0`, the results will not be fully deterministic. + +- `--top-k: optional number` + + Body param: Only sample from the top K options for each subsequent token. + + Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--top-p: optional number` + + Body param: Use nucleus sampling. + + In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `completion: object { id, completion, model, 2 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `completion: string` + + The resulting completion up to and excluding the stop sequences. + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `stop_reason: string` + + The reason that we stopped. + + This may be one the following values: + + * `"stop_sequence"`: we reached a stop sequence — either provided by you via the `stop_sequences` parameter, or a stop sequence built into the model + * `"max_tokens"`: we exceeded `max_tokens_to_sample` or the model's maximum + + - `type: "completion"` + + Object type. + + For Text Completions, this is always `"completion"`. + +### Example + +```cli +ant completions create \ + --api-key my-anthropic-api-key \ + --max-tokens-to-sample 256 \ + --model claude-mythos-preview \ + --prompt ' + +Human: Hello, world! + +Assistant:' +``` diff --git a/content/en/api/cli/messages.md b/content/en/api/cli/messages.md index ee46967ae..4509829b4 100644 --- a/content/en/api/cli/messages.md +++ b/content/en/api/cli/messages.md @@ -1 +1,21779 @@ -Not Found - Claude API Docs
                                                                    \ No newline at end of file +# Messages + +## Create + +`$ ant messages create` + +**post** `/v1/messages` + +Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. + +The Messages API can be used for either single queries or stateless multi-turn conversations. + +Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup) + +### Parameters + +- `--max-tokens: number` + + The maximum number of tokens to generate before stopping. + + Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. + + Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. + +- `--message: array of MessageParam` + + Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + +- `--model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--cache-control: optional object { type, ttl }` + + Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--container: optional string` + + Container identifier for reuse across requests. + +- `--inference-geo: optional string` + + Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. + +- `--metadata: optional object { user_id }` + + An object describing metadata about the request. + +- `--output-config: optional object { effort, format }` + + Configuration options for the model's output, such as the output format. + +- `--service-tier: optional "auto" or "standard_only"` + + Determines whether to use priority capacity (if available) or standard capacity for this request. + + Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. + +- `--stop-sequence: optional array of string` + + Custom text sequences that will cause the model to stop generating. + + Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. + + If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. + +- `--system: optional string or array of TextBlockParam` + + System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + +- `--temperature: optional number` + + Amount of randomness injected into the response. + + Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. + + Note that even with `temperature` of `0.0`, the results will not be fully deterministic. + +- `--thinking: optional ThinkingConfigEnabled or ThinkingConfigDisabled or ThinkingConfigAdaptive` + + Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + +- `--tool-choice: optional ToolChoiceAuto or ToolChoiceAny or ToolChoiceTool or ToolChoiceNone` + + How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + +- `--tool: optional array of ToolUnion` + + Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + +- `--top-k: optional number` + + Only sample from the top K options for each subsequent token. + + Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--top-p: optional number` + + Use nucleus sampling. + + In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +### Returns + +- `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + +### Example + +```cli +ant messages create \ + --api-key my-anthropic-api-key \ + --max-tokens 1024 \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-opus-4-6 +``` + +## Count Tokens + +`$ ant messages count-tokens` + +**post** `/v1/messages/count_tokens` + +Count the number of tokens in a Message. + +The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it. + +Learn more about token counting in our [user guide](https://docs.claude.com/en/docs/build-with-claude/token-counting) + +### Parameters + +- `--message: array of MessageParam` + + Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + +- `--model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--cache-control: optional object { type, ttl }` + + Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--output-config: optional object { effort, format }` + + Configuration options for the model's output, such as the output format. + +- `--system: optional string or array of TextBlockParam` + + System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + +- `--thinking: optional ThinkingConfigEnabled or ThinkingConfigDisabled or ThinkingConfigAdaptive` + + Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + +- `--tool-choice: optional ToolChoiceAuto or ToolChoiceAny or ToolChoiceTool or ToolChoiceNone` + + How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + +- `--tool: optional array of MessageCountTokensTool` + + Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + +### Returns + +- `message_tokens_count: object { input_tokens }` + + - `input_tokens: number` + + The total number of tokens across the provided list of messages, system prompt, and tools. + +### Example + +```cli +ant messages count-tokens \ + --api-key my-anthropic-api-key \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-mythos-preview +``` + +## Domain Types + +### Base64 Image Source + +- `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + +### Base64 PDF Source + +- `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + +### Bash Code Execution Output Block + +- `bash_code_execution_output_block: object { file_id, type }` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + +### Bash Code Execution Output Block Param + +- `bash_code_execution_output_block_param: object { file_id, type }` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + +### Bash Code Execution Result Block + +- `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + +### Bash Code Execution Result Block Param + +- `bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + +### Bash Code Execution Tool Result Block + +- `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + +### Bash Code Execution Tool Result Block Param + +- `bash_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam` + + - `bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Bash Code Execution Tool Result Error + +- `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + +### Bash Code Execution Tool Result Error Code + +- `bash_code_execution_tool_result_error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + +### Bash Code Execution Tool Result Error Param + +- `bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + +### Cache Control Ephemeral + +- `cache_control_ephemeral: object { type, ttl }` + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Cache Creation + +- `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + +### Citation Char Location + +- `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + +### Citation Char Location Param + +- `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + +### Citation Content Block Location + +- `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + +### Citation Content Block Location Param + +- `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + +### Citation Page Location + +- `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + +### Citation Page Location Param + +- `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + +### Citation Search Result Location Param + +- `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Citation Web Search Result Location Param + +- `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + +### Citations Config + +- `citations_config: object { enabled }` + + - `enabled: boolean` + +### Citations Config Param + +- `citations_config_param: object { enabled }` + + - `enabled: optional boolean` + +### Citations Delta + +- `citations_delta: object { citation, type }` + + - `citation: CitationCharLocation or CitationPageLocation or CitationContentBlockLocation or 2 more` + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + +### Citations Search Result Location + +- `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Citations Web Search Result Location + +- `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + +### Code Execution Output Block + +- `code_execution_output_block: object { file_id, type }` + + - `file_id: string` + + - `type: "code_execution_output"` + +### Code Execution Output Block Param + +- `code_execution_output_block_param: object { file_id, type }` + + - `file_id: string` + + - `type: "code_execution_output"` + +### Code Execution Result Block + +- `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + +### Code Execution Result Block Param + +- `code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + +### Code Execution Tool 20250522 + +- `code_execution_tool_20250522: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250522"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Code Execution Tool 20250825 + +- `code_execution_tool_20250825: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250825"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Code Execution Tool 20260120 + +- `code_execution_tool_20260120: object { name, type, allowed_callers, 3 more }` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20260120"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Code Execution Tool Result Block + +- `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + +### Code Execution Tool Result Block Content + +- `code_execution_tool_result_block_content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Code Execution Tool Result Block Param + +- `code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: CodeExecutionToolResultErrorParam or CodeExecutionResultBlockParam or EncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Code Execution Tool Result Block Param Content + +- `code_execution_tool_result_block_param_content: CodeExecutionToolResultErrorParam or CodeExecutionResultBlockParam or EncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Code Execution Tool Result Error + +- `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + +### Code Execution Tool Result Error Code + +- `code_execution_tool_result_error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + +### Code Execution Tool Result Error Param + +- `code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + +### Container + +- `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + +### Container Upload Block + +- `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + +### Container Upload Block Param + +- `container_upload_block_param: object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Content Block + +- `content_block: TextBlock or ThinkingBlock or RedactedThinkingBlock or 9 more` + + Response model for a file uploaded to the container. + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + +### Content Block Param + +- `content_block_param: TextBlockParam or ImageBlockParam or DocumentBlockParam or 13 more` + + Regular text content. + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `document_block_param: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `thinking_block_param: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block_param: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `document_block_param: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + + - `server_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `web_search_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: array of WebSearchResultBlockParam or WebSearchToolRequestError` + + - `web_search_tool_result_block_item: array of WebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `web_fetch_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam` + + - `web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: CodeExecutionToolResultErrorParam or CodeExecutionResultBlockParam or EncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `bash_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam` + + - `bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `text_editor_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam` + + - `text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `tool_search_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam` + + - `tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `container_upload_block_param: object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Content Block Source + +- `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + +### Content Block Source Content + +- `content_block_source_content: TextBlockParam or ImageBlockParam` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Direct Caller + +- `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + +### Document Block + +- `document_block: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + +### Document Block Param + +- `document_block_param: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + +### Encrypted Code Execution Result Block + +- `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Encrypted Code Execution Result Block Param + +- `encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Image Block Param + +- `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Input JSON Delta + +- `input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + +### JSON Output Format + +- `json_output_format: object { schema, type }` + + - `schema: map[unknown]` + + The JSON schema of the format + + - `type: "json_schema"` + +### Memory Tool 20250818 + +- `memory_tool_20250818: object { name, type, allowed_callers, 4 more }` + + - `name: "memory"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "memory_20250818"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Message + +- `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + +### Message Count Tokens Tool + +- `message_count_tokens_tool: Tool or ToolBash20250124 or CodeExecutionTool20250522 or 13 more` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `tool: object { input_schema, name, allowed_callers, 7 more }` + + - `input_schema: object { type, properties, required }` + + [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + + This defines the shape of the `input` that your tool accepts and that the model will produce. + + - `type: "object"` + + - `properties: optional map[unknown]` + + - `required: optional array of string` + + - `name: string` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `description: optional string` + + Description of what this tool does. + + Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + + - `eager_input_streaming: optional boolean` + + Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `type: optional "custom"` + + - `"custom"` + + - `tool_bash_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `code_execution_tool_20250522: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250522"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `code_execution_tool_20250825: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250825"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `code_execution_tool_20260120: object { name, type, allowed_callers, 3 more }` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20260120"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `memory_tool_20250818: object { name, type, allowed_callers, 4 more }` + + - `name: "memory"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "memory_20250818"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_text_editor_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_text_editor_20250429: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250429"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_text_editor_20250728: object { name, type, allowed_callers, 5 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250728"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `max_characters: optional number` + + Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `web_search_tool_20250305: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20250305"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `web_fetch_tool_20250910: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20250910"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `web_search_tool_20260209: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `web_fetch_tool_20260209: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `web_fetch_tool_20260309: object { name, type, allowed_callers, 9 more }` + + Web fetch tool with use_cache parameter for bypassing cached content. + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260309"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `use_cache: optional boolean` + + Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. + + - `tool_search_tool_bm25_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_bm25"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + + - `"tool_search_tool_bm25"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_search_tool_regex_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_regex"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + + - `"tool_search_tool_regex"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Message Delta Usage + +- `message_delta_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + - `cache_creation_input_tokens: number` + + The cumulative number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The cumulative number of input tokens read from the cache. + + - `input_tokens: number` + + The cumulative number of input tokens which were used. + + - `output_tokens: number` + + The cumulative number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + +### Message Param + +- `message_param: object { content, role }` + + - `content: array of ContentBlockParam` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `document_block_param: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `thinking_block_param: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block_param: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `document_block_param: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + + - `server_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `web_search_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: array of WebSearchResultBlockParam or WebSearchToolRequestError` + + - `web_search_tool_result_block_item: array of WebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `web_fetch_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam` + + - `web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: CodeExecutionToolResultErrorParam or CodeExecutionResultBlockParam or EncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `bash_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam` + + - `bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `text_editor_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam` + + - `text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `tool_search_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam` + + - `tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `container_upload_block_param: object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `role: "user" or "assistant"` + + - `"user"` + + - `"assistant"` + +### Message Tokens Count + +- `message_tokens_count: object { input_tokens }` + + - `input_tokens: number` + + The total number of tokens across the provided list of messages, system prompt, and tools. + +### Metadata + +- `metadata: object { user_id }` + + - `user_id: optional string` + + An external identifier for the user who is associated with the request. + + This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. + +### Output Config + +- `output_config: object { effort, format }` + + - `effort: optional "low" or "medium" or "high" or "max"` + + All possible effort levels. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"max"` + + - `format: optional object { schema, type }` + + A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + - `schema: map[unknown]` + + The JSON schema of the format + + - `type: "json_schema"` + +### Plain Text Source + +- `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + +### Raw Content Block Delta + +- `raw_content_block_delta: TextDelta or InputJSONDelta or CitationsDelta or 2 more` + + - `text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + + - `input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + + - `citations_delta: object { citation, type }` + + - `citation: CitationCharLocation or CitationPageLocation or CitationContentBlockLocation or 2 more` + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + + - `thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + + - `signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + +### Raw Content Block Delta Event + +- `raw_content_block_delta_event: object { delta, index, type }` + + - `delta: TextDelta or InputJSONDelta or CitationsDelta or 2 more` + + - `text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + + - `input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + + - `citations_delta: object { citation, type }` + + - `citation: CitationCharLocation or CitationPageLocation or CitationContentBlockLocation or 2 more` + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + + - `thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + + - `signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + + - `index: number` + + - `type: "content_block_delta"` + +### Raw Content Block Start Event + +- `raw_content_block_start_event: object { content_block, index, type }` + + - `content_block: TextBlock or ThinkingBlock or RedactedThinkingBlock or 9 more` + + Response model for a file uploaded to the container. + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `index: number` + + - `type: "content_block_start"` + +### Raw Content Block Stop Event + +- `raw_content_block_stop_event: object { index, type }` + + - `index: number` + + - `type: "content_block_stop"` + +### Raw Message Delta Event + +- `raw_message_delta_event: object { delta, type, usage }` + + - `delta: object { container, stop_details, stop_reason, stop_sequence }` + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + - `type: "message_delta"` + + - `usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation_input_tokens: number` + + The cumulative number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The cumulative number of input tokens read from the cache. + + - `input_tokens: number` + + The cumulative number of input tokens which were used. + + - `output_tokens: number` + + The cumulative number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + +### Raw Message Start Event + +- `raw_message_start_event: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "message_start"` + +### Raw Message Stop Event + +- `raw_message_stop_event: object { type }` + + - `type: "message_stop"` + +### Raw Message Stream Event + +- `raw_message_stream_event: RawMessageStartEvent or RawMessageDeltaEvent or RawMessageStopEvent or 3 more` + + - `raw_message_start_event: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "message_start"` + + - `raw_message_delta_event: object { delta, type, usage }` + + - `delta: object { container, stop_details, stop_reason, stop_sequence }` + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + - `type: "message_delta"` + + - `usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation_input_tokens: number` + + The cumulative number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The cumulative number of input tokens read from the cache. + + - `input_tokens: number` + + The cumulative number of input tokens which were used. + + - `output_tokens: number` + + The cumulative number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `raw_message_stop_event: object { type }` + + - `type: "message_stop"` + + - `raw_content_block_start_event: object { content_block, index, type }` + + - `content_block: TextBlock or ThinkingBlock or RedactedThinkingBlock or 9 more` + + Response model for a file uploaded to the container. + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `index: number` + + - `type: "content_block_start"` + + - `raw_content_block_delta_event: object { delta, index, type }` + + - `delta: TextDelta or InputJSONDelta or CitationsDelta or 2 more` + + - `text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + + - `input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + + - `citations_delta: object { citation, type }` + + - `citation: CitationCharLocation or CitationPageLocation or CitationContentBlockLocation or 2 more` + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + + - `thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + + - `signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + + - `index: number` + + - `type: "content_block_delta"` + + - `raw_content_block_stop_event: object { index, type }` + + - `index: number` + + - `type: "content_block_stop"` + +### Redacted Thinking Block + +- `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + +### Redacted Thinking Block Param + +- `redacted_thinking_block_param: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + +### Refusal Stop Details + +- `refusal_stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + +### Search Result Block Param + +- `search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + +### Server Tool Caller + +- `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + +### Server Tool Caller 20260120 + +- `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Server Tool Usage + +- `server_tool_usage: object { web_fetch_requests, web_search_requests }` + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + +### Server Tool Use Block + +- `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + +### Server Tool Use Block Param + +- `server_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Signature Delta + +- `signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + +### Stop Reason + +- `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + +### Text Block + +- `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + +### Text Block Param + +- `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Text Citation + +- `text_citation: CitationCharLocation or CitationPageLocation or CitationContentBlockLocation or 2 more` + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Text Citation Param + +- `text_citation_param: CitationCharLocationParam or CitationPageLocationParam or CitationContentBlockLocationParam or 2 more` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Text Delta + +- `text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + +### Text Editor Code Execution Create Result Block + +- `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + +### Text Editor Code Execution Create Result Block Param + +- `text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + +### Text Editor Code Execution Str Replace Result Block + +- `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + +### Text Editor Code Execution Str Replace Result Block Param + +- `text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + +### Text Editor Code Execution Tool Result Block + +- `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + +### Text Editor Code Execution Tool Result Block Param + +- `text_editor_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam` + + - `text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Text Editor Code Execution Tool Result Error + +- `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + +### Text Editor Code Execution Tool Result Error Code + +- `text_editor_code_execution_tool_result_error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + +### Text Editor Code Execution Tool Result Error Param + +- `text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + +### Text Editor Code Execution View Result Block + +- `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + +### Text Editor Code Execution View Result Block Param + +- `text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + +### Thinking Block + +- `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + +### Thinking Block Param + +- `thinking_block_param: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + +### Thinking Config Adaptive + +- `thinking_config_adaptive: object { type, display }` + + - `type: "adaptive"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +### Thinking Config Disabled + +- `thinking_config_disabled: object { type }` + + - `type: "disabled"` + +### Thinking Config Enabled + +- `thinking_config_enabled: object { budget_tokens, type, display }` + + - `budget_tokens: number` + + Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. + + Must be ≥1024 and less than `max_tokens`. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `type: "enabled"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +### Thinking Config Param + +- `thinking_config_param: ThinkingConfigEnabled or ThinkingConfigDisabled or ThinkingConfigAdaptive` + + Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `thinking_config_enabled: object { budget_tokens, type, display }` + + - `budget_tokens: number` + + Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. + + Must be ≥1024 and less than `max_tokens`. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `type: "enabled"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + + - `thinking_config_disabled: object { type }` + + - `type: "disabled"` + + - `thinking_config_adaptive: object { type, display }` + + - `type: "adaptive"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +### Thinking Delta + +- `thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + +### Tool + +- `tool: object { input_schema, name, allowed_callers, 7 more }` + + - `input_schema: object { type, properties, required }` + + [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + + This defines the shape of the `input` that your tool accepts and that the model will produce. + + - `type: "object"` + + - `properties: optional map[unknown]` + + - `required: optional array of string` + + - `name: string` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `description: optional string` + + Description of what this tool does. + + Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + + - `eager_input_streaming: optional boolean` + + Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `type: optional "custom"` + + - `"custom"` + +### Tool Bash 20250124 + +- `tool_bash_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Choice + +- `tool_choice: ToolChoiceAuto or ToolChoiceAny or ToolChoiceTool or ToolChoiceNone` + + How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + + - `tool_choice_auto: object { type, disable_parallel_tool_use }` + + The model will automatically decide whether to use tools. + + - `type: "auto"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output at most one tool use. + + - `tool_choice_any: object { type, disable_parallel_tool_use }` + + The model will use any available tools. + + - `type: "any"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + + - `tool_choice_tool: object { name, type, disable_parallel_tool_use }` + + The model will use the specified tool with `tool_choice.name`. + + - `name: string` + + The name of the tool to use. + + - `type: "tool"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + + - `tool_choice_none: object { type }` + + The model will not be allowed to use tools. + + - `type: "none"` + +### Tool Choice Any + +- `tool_choice_any: object { type, disable_parallel_tool_use }` + + The model will use any available tools. + + - `type: "any"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + +### Tool Choice Auto + +- `tool_choice_auto: object { type, disable_parallel_tool_use }` + + The model will automatically decide whether to use tools. + + - `type: "auto"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output at most one tool use. + +### Tool Choice None + +- `tool_choice_none: object { type }` + + The model will not be allowed to use tools. + + - `type: "none"` + +### Tool Choice Tool + +- `tool_choice_tool: object { name, type, disable_parallel_tool_use }` + + The model will use the specified tool with `tool_choice.name`. + + - `name: string` + + The name of the tool to use. + + - `type: "tool"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + +### Tool Reference Block + +- `tool_reference_block: object { tool_name, type }` + + - `tool_name: string` + + - `type: "tool_reference"` + +### Tool Reference Block Param + +- `tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Tool Result Block Param + +- `tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `document_block_param: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + +### Tool Search Tool Bm25 20251119 + +- `tool_search_tool_bm25_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_bm25"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + + - `"tool_search_tool_bm25"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Search Tool Regex 20251119 + +- `tool_search_tool_regex_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_regex"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + + - `"tool_search_tool_regex"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Search Tool Result Block + +- `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + +### Tool Search Tool Result Block Param + +- `tool_search_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam` + + - `tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Tool Search Tool Result Error + +- `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + +### Tool Search Tool Result Error Code + +- `tool_search_tool_result_error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + +### Tool Search Tool Result Error Param + +- `tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + +### Tool Search Tool Search Result Block + +- `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + +### Tool Search Tool Search Result Block Param + +- `tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + +### Tool Text Editor 20250124 + +- `tool_text_editor_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Text Editor 20250429 + +- `tool_text_editor_20250429: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250429"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Text Editor 20250728 + +- `tool_text_editor_20250728: object { name, type, allowed_callers, 5 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250728"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `max_characters: optional number` + + Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Union + +- `tool_union: Tool or ToolBash20250124 or CodeExecutionTool20250522 or 13 more` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `tool: object { input_schema, name, allowed_callers, 7 more }` + + - `input_schema: object { type, properties, required }` + + [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + + This defines the shape of the `input` that your tool accepts and that the model will produce. + + - `type: "object"` + + - `properties: optional map[unknown]` + + - `required: optional array of string` + + - `name: string` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `description: optional string` + + Description of what this tool does. + + Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + + - `eager_input_streaming: optional boolean` + + Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `type: optional "custom"` + + - `"custom"` + + - `tool_bash_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `code_execution_tool_20250522: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250522"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `code_execution_tool_20250825: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250825"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `code_execution_tool_20260120: object { name, type, allowed_callers, 3 more }` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20260120"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `memory_tool_20250818: object { name, type, allowed_callers, 4 more }` + + - `name: "memory"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "memory_20250818"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_text_editor_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_text_editor_20250429: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250429"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_text_editor_20250728: object { name, type, allowed_callers, 5 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250728"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `max_characters: optional number` + + Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `web_search_tool_20250305: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20250305"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `web_fetch_tool_20250910: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20250910"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `web_search_tool_20260209: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `web_fetch_tool_20260209: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `web_fetch_tool_20260309: object { name, type, allowed_callers, 9 more }` + + Web fetch tool with use_cache parameter for bypassing cached content. + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260309"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `use_cache: optional boolean` + + Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. + + - `tool_search_tool_bm25_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_bm25"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + + - `"tool_search_tool_bm25"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_search_tool_regex_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_regex"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + + - `"tool_search_tool_regex"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Use Block + +- `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + +### Tool Use Block Param + +- `tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### URL Image Source + +- `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + +### URL PDF Source + +- `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + +### Usage + +- `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + +### User Location + +- `user_location: object { type, city, country, 2 more }` + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + +### Web Fetch Block + +- `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + +### Web Fetch Block Param + +- `web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + +### Web Fetch Tool 20250910 + +- `web_fetch_tool_20250910: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20250910"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Web Fetch Tool 20260209 + +- `web_fetch_tool_20260209: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Web Fetch Tool 20260309 + +- `web_fetch_tool_20260309: object { name, type, allowed_callers, 9 more }` + + Web fetch tool with use_cache parameter for bypassing cached content. + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260309"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `use_cache: optional boolean` + + Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. + +### Web Fetch Tool Result Block + +- `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + +### Web Fetch Tool Result Block Param + +- `web_fetch_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam` + + - `web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Web Fetch Tool Result Error Block + +- `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + +### Web Fetch Tool Result Error Block Param + +- `web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + +### Web Fetch Tool Result Error Code + +- `web_fetch_tool_result_error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + +### Web Search Result Block + +- `web_search_result_block: object { encrypted_content, page_age, title, 2 more }` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + +### Web Search Result Block Param + +- `web_search_result_block_param: object { encrypted_content, title, type, 2 more }` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + +### Web Search Tool 20250305 + +- `web_search_tool_20250305: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20250305"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + +### Web Search Tool 20260209 + +- `web_search_tool_20260209: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + +### Web Search Tool Request Error + +- `web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + +### Web Search Tool Result Block + +- `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + +### Web Search Tool Result Block Content + +- `web_search_tool_result_block_content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + +### Web Search Tool Result Block Param + +- `web_search_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: array of WebSearchResultBlockParam or WebSearchToolRequestError` + + - `web_search_tool_result_block_item: array of WebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Web Search Tool Result Block Param Content + +- `web_search_tool_result_block_param_content: array of WebSearchResultBlockParam or WebSearchToolRequestError` + + - `web_search_tool_result_block_item: array of WebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + +### Web Search Tool Result Error + +- `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + +### Web Search Tool Result Error Code + +- `web_search_tool_result_error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + +# Batches + +## Create + +`$ ant messages:batches create` + +**post** `/v1/messages/batches` + +Send a batch of Message creation requests. + +The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--request: array of object { custom_id, params }` + + List of requests for prompt completion. Each is an individual request to create a Message. + +### Returns + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant messages:batches create \ + --api-key my-anthropic-api-key \ + --request '{custom_id: my-custom-id-1, params: {max_tokens: 1024, messages: [{content: [{text: x, type: text}], role: user}], model: claude-opus-4-6}}' +``` + +## Retrieve + +`$ ant messages:batches retrieve` + +**get** `/v1/messages/batches/{message_batch_id}` + +This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant messages:batches retrieve \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## List + +`$ ant messages:batches list` + +**get** `/v1/messages/batches` + +List all Message Batches within a Workspace. Most recently created batches are returned first. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--after-id: optional string` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +### Returns + +- `ListResponse_MessageBatch_: object { data, first_id, has_more, last_id }` + + - `data: array of MessageBatch` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant messages:batches list \ + --api-key my-anthropic-api-key +``` + +## Cancel + +`$ ant messages:batches cancel` + +**post** `/v1/messages/batches/{message_batch_id}/cancel` + +Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. + +The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant messages:batches cancel \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Delete + +`$ ant messages:batches delete` + +**delete** `/v1/messages/batches/{message_batch_id}` + +Delete a Message Batch. + +Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Example + +```cli +ant messages:batches delete \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Results + +`$ ant messages:batches results` + +**get** `/v1/messages/batches/{message_batch_id}/results` + +Streams the results of a Message Batch as a `.jsonl` file. + +Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: MessageBatchSucceededResult or MessageBatchErroredResult or MessageBatchCanceledResult or MessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` + + - `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Example + +```cli +ant messages:batches results \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Domain Types + +### Deleted Message Batch + +- `deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Message Batch + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Message Batch Canceled Result + +- `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + +### Message Batch Errored Result + +- `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + +### Message Batch Expired Result + +- `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Message Batch Individual Response + +- `message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: MessageBatchSucceededResult or MessageBatchErroredResult or MessageBatchCanceledResult or MessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` + + - `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Message Batch Request Counts + +- `message_batch_request_counts: object { canceled, errored, expired, 2 more }` + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + +### Message Batch Result + +- `message_batch_result: MessageBatchSucceededResult or MessageBatchErroredResult or MessageBatchCanceledResult or MessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` + + - `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Message Batch Succeeded Result + +- `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` diff --git a/content/en/api/cli/messages/batches.md b/content/en/api/cli/messages/batches.md index 5d627650b..b17075cf4 100644 --- a/content/en/api/cli/messages/batches.md +++ b/content/en/api/cli/messages/batches.md @@ -1 +1,4250 @@ -Not Found - Claude API Docs
                                                                      \ No newline at end of file +# Batches + +## Create + +`$ ant messages:batches create` + +**post** `/v1/messages/batches` + +Send a batch of Message creation requests. + +The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--request: array of object { custom_id, params }` + + List of requests for prompt completion. Each is an individual request to create a Message. + +### Returns + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant messages:batches create \ + --api-key my-anthropic-api-key \ + --request '{custom_id: my-custom-id-1, params: {max_tokens: 1024, messages: [{content: [{text: x, type: text}], role: user}], model: claude-opus-4-6}}' +``` + +## Retrieve + +`$ ant messages:batches retrieve` + +**get** `/v1/messages/batches/{message_batch_id}` + +This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant messages:batches retrieve \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## List + +`$ ant messages:batches list` + +**get** `/v1/messages/batches` + +List all Message Batches within a Workspace. Most recently created batches are returned first. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--after-id: optional string` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +### Returns + +- `ListResponse_MessageBatch_: object { data, first_id, has_more, last_id }` + + - `data: array of MessageBatch` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant messages:batches list \ + --api-key my-anthropic-api-key +``` + +## Cancel + +`$ ant messages:batches cancel` + +**post** `/v1/messages/batches/{message_batch_id}/cancel` + +Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. + +The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant messages:batches cancel \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Delete + +`$ ant messages:batches delete` + +**delete** `/v1/messages/batches/{message_batch_id}` + +Delete a Message Batch. + +Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Example + +```cli +ant messages:batches delete \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Results + +`$ ant messages:batches results` + +**get** `/v1/messages/batches/{message_batch_id}/results` + +Streams the results of a Message Batch as a `.jsonl` file. + +Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: MessageBatchSucceededResult or MessageBatchErroredResult or MessageBatchCanceledResult or MessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` + + - `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Example + +```cli +ant messages:batches results \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Domain Types + +### Deleted Message Batch + +- `deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Message Batch + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Message Batch Canceled Result + +- `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + +### Message Batch Errored Result + +- `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + +### Message Batch Expired Result + +- `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Message Batch Individual Response + +- `message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: MessageBatchSucceededResult or MessageBatchErroredResult or MessageBatchCanceledResult or MessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` + + - `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Message Batch Request Counts + +- `message_batch_request_counts: object { canceled, errored, expired, 2 more }` + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + +### Message Batch Result + +- `message_batch_result: MessageBatchSucceededResult or MessageBatchErroredResult or MessageBatchCanceledResult or MessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` + + - `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Message Batch Succeeded Result + +- `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` diff --git a/content/en/api/cli/messages/batches/cancel.md b/content/en/api/cli/messages/batches/cancel.md index 81a0014ec..250cfedea 100644 --- a/content/en/api/cli/messages/batches/cancel.md +++ b/content/en/api/cli/messages/batches/cancel.md @@ -1 +1,113 @@ -Not Found - Claude API Docs
                                                                        \ No newline at end of file +## Cancel + +`$ ant messages:batches cancel` + +**post** `/v1/messages/batches/{message_batch_id}/cancel` + +Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. + +The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant messages:batches cancel \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` diff --git a/content/en/api/cli/messages/batches/create.md b/content/en/api/cli/messages/batches/create.md index 9425d5356..34d8becb7 100644 --- a/content/en/api/cli/messages/batches/create.md +++ b/content/en/api/cli/messages/batches/create.md @@ -1 +1,113 @@ -Not Found - Claude API Docs
                                                                          \ No newline at end of file +## Create + +`$ ant messages:batches create` + +**post** `/v1/messages/batches` + +Send a batch of Message creation requests. + +The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--request: array of object { custom_id, params }` + + List of requests for prompt completion. Each is an individual request to create a Message. + +### Returns + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant messages:batches create \ + --api-key my-anthropic-api-key \ + --request '{custom_id: my-custom-id-1, params: {max_tokens: 1024, messages: [{content: [{text: x, type: text}], role: user}], model: claude-opus-4-6}}' +``` diff --git a/content/en/api/cli/messages/batches/delete.md b/content/en/api/cli/messages/batches/delete.md index 92909acc6..23d487a8e 100644 --- a/content/en/api/cli/messages/batches/delete.md +++ b/content/en/api/cli/messages/batches/delete.md @@ -1 +1,39 @@ -Not Found - Claude API Docs
                                                                            \ No newline at end of file +## Delete + +`$ ant messages:batches delete` + +**delete** `/v1/messages/batches/{message_batch_id}` + +Delete a Message Batch. + +Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Example + +```cli +ant messages:batches delete \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` diff --git a/content/en/api/cli/messages/batches/list.md b/content/en/api/cli/messages/batches/list.md index f52ea9152..5b26ceb4b 100644 --- a/content/en/api/cli/messages/batches/list.md +++ b/content/en/api/cli/messages/batches/list.md @@ -1 +1,134 @@ -Not Found - Claude API Docs
                                                                              \ No newline at end of file +## List + +`$ ant messages:batches list` + +**get** `/v1/messages/batches` + +List all Message Batches within a Workspace. Most recently created batches are returned first. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--after-id: optional string` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +### Returns + +- `ListResponse_MessageBatch_: object { data, first_id, has_more, last_id }` + + - `data: array of MessageBatch` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant messages:batches list \ + --api-key my-anthropic-api-key +``` diff --git a/content/en/api/cli/messages/batches/results.md b/content/en/api/cli/messages/batches/results.md index d45d10752..7f1dde6c6 100644 --- a/content/en/api/cli/messages/batches/results.md +++ b/content/en/api/cli/messages/batches/results.md @@ -1 +1,923 @@ -Not Found - Claude API Docs
                                                                                \ No newline at end of file +## Results + +`$ ant messages:batches results` + +**get** `/v1/messages/batches/{message_batch_id}/results` + +Streams the results of a Message Batch as a `.jsonl` file. + +Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: MessageBatchSucceededResult or MessageBatchErroredResult or MessageBatchCanceledResult or MessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` + + - `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Example + +```cli +ant messages:batches results \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` diff --git a/content/en/api/cli/messages/batches/retrieve.md b/content/en/api/cli/messages/batches/retrieve.md index 6fce047c0..70b060159 100644 --- a/content/en/api/cli/messages/batches/retrieve.md +++ b/content/en/api/cli/messages/batches/retrieve.md @@ -1 +1,111 @@ -Not Found - Claude API Docs
                                                                                  \ No newline at end of file +## Retrieve + +`$ ant messages:batches retrieve` + +**get** `/v1/messages/batches/{message_batch_id}` + +This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant messages:batches retrieve \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` diff --git a/content/en/api/cli/messages/count_tokens.md b/content/en/api/cli/messages/count_tokens.md index ba5e1ff0c..261ea3f8a 100644 --- a/content/en/api/cli/messages/count_tokens.md +++ b/content/en/api/cli/messages/count_tokens.md @@ -1 +1,177 @@ -Not Found - Claude API Docs
                                                                                    \ No newline at end of file +## Count Tokens + +`$ ant messages count-tokens` + +**post** `/v1/messages/count_tokens` + +Count the number of tokens in a Message. + +The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it. + +Learn more about token counting in our [user guide](https://docs.claude.com/en/docs/build-with-claude/token-counting) + +### Parameters + +- `--message: array of MessageParam` + + Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + +- `--model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--cache-control: optional object { type, ttl }` + + Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--output-config: optional object { effort, format }` + + Configuration options for the model's output, such as the output format. + +- `--system: optional string or array of TextBlockParam` + + System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + +- `--thinking: optional ThinkingConfigEnabled or ThinkingConfigDisabled or ThinkingConfigAdaptive` + + Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + +- `--tool-choice: optional ToolChoiceAuto or ToolChoiceAny or ToolChoiceTool or ToolChoiceNone` + + How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + +- `--tool: optional array of MessageCountTokensTool` + + Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + +### Returns + +- `message_tokens_count: object { input_tokens }` + + - `input_tokens: number` + + The total number of tokens across the provided list of messages, system prompt, and tools. + +### Example + +```cli +ant messages count-tokens \ + --api-key my-anthropic-api-key \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-mythos-preview +``` diff --git a/content/en/api/cli/messages/create.md b/content/en/api/cli/messages/create.md index 0bbbc48e2..251bc4a5e 100644 --- a/content/en/api/cli/messages/create.md +++ b/content/en/api/cli/messages/create.md @@ -1 +1,1032 @@ -Not Found - Claude API Docs
                                                                                      \ No newline at end of file +## Create + +`$ ant messages create` + +**post** `/v1/messages` + +Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. + +The Messages API can be used for either single queries or stateless multi-turn conversations. + +Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup) + +### Parameters + +- `--max-tokens: number` + + The maximum number of tokens to generate before stopping. + + Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. + + Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. + +- `--message: array of MessageParam` + + Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + +- `--model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--cache-control: optional object { type, ttl }` + + Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--container: optional string` + + Container identifier for reuse across requests. + +- `--inference-geo: optional string` + + Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. + +- `--metadata: optional object { user_id }` + + An object describing metadata about the request. + +- `--output-config: optional object { effort, format }` + + Configuration options for the model's output, such as the output format. + +- `--service-tier: optional "auto" or "standard_only"` + + Determines whether to use priority capacity (if available) or standard capacity for this request. + + Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. + +- `--stop-sequence: optional array of string` + + Custom text sequences that will cause the model to stop generating. + + Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. + + If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. + +- `--system: optional string or array of TextBlockParam` + + System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + +- `--temperature: optional number` + + Amount of randomness injected into the response. + + Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. + + Note that even with `temperature` of `0.0`, the results will not be fully deterministic. + +- `--thinking: optional ThinkingConfigEnabled or ThinkingConfigDisabled or ThinkingConfigAdaptive` + + Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + +- `--tool-choice: optional ToolChoiceAuto or ToolChoiceAny or ToolChoiceTool or ToolChoiceNone` + + How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + +- `--tool: optional array of ToolUnion` + + Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + +- `--top-k: optional number` + + Only sample from the top K options for each subsequent token. + + Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--top-p: optional number` + + Use nucleus sampling. + + In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +### Returns + +- `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + +### Example + +```cli +ant messages create \ + --api-key my-anthropic-api-key \ + --max-tokens 1024 \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-opus-4-6 +``` diff --git a/content/en/api/cli/models.md b/content/en/api/cli/models.md index 236260cd6..05eb18c53 100644 --- a/content/en/api/cli/models.md +++ b/content/en/api/cli/models.md @@ -1 +1,920 @@ -Not Found - Claude API Docs
                                                                                        \ No newline at end of file +# Models + +## List + +`$ ant models list` + +**get** `/v1/models` + +List available models. + +The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first. + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `ListResponse_ModelInfo_: object { data, first_id, has_more, last_id }` + + - `data: array of ModelInfo` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant models list \ + --api-key my-anthropic-api-key +``` + +## Retrieve + +`$ ant models retrieve` + +**get** `/v1/models/{model_id}` + +Get a specific model. + +The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID. + +### Parameters + +- `--model-id: string` + + Model identifier or alias. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `model_info: object { id, capabilities, created_at, 4 more }` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + +### Example + +```cli +ant models retrieve \ + --api-key my-anthropic-api-key \ + --model-id model_id +``` + +## Domain Types + +### Capability Support + +- `capability_support: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Context Management Capability + +- `context_management_capability: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management capability details. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Effort Capability + +- `effort_capability: object { high, low, max, 2 more }` + + Effort (reasoning_effort) capability details. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Model Capabilities + +- `model_capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Model Info + +- `model_info: object { id, capabilities, created_at, 4 more }` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + +### Thinking Capability + +- `thinking_capability: object { supported, types }` + + Thinking capability details. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + +### Thinking Types + +- `thinking_types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. diff --git a/content/en/api/cli/models/list.md b/content/en/api/cli/models/list.md index d906e3717..957f9ebe6 100644 --- a/content/en/api/cli/models/list.md +++ b/content/en/api/cli/models/list.md @@ -1 +1,232 @@ -Not Found - Claude API Docs
                                                                                          \ No newline at end of file +## List + +`$ ant models list` + +**get** `/v1/models` + +List available models. + +The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first. + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `ListResponse_ModelInfo_: object { data, first_id, has_more, last_id }` + + - `data: array of ModelInfo` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant models list \ + --api-key my-anthropic-api-key +``` diff --git a/content/en/api/cli/models/retrieve.md b/content/en/api/cli/models/retrieve.md index 4628c12f4..96fb501cd 100644 --- a/content/en/api/cli/models/retrieve.md +++ b/content/en/api/cli/models/retrieve.md @@ -1 +1,209 @@ -Not Found - Claude API Docs
                                                                                            \ No newline at end of file +## Retrieve + +`$ ant models retrieve` + +**get** `/v1/models/{model_id}` + +Get a specific model. + +The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID. + +### Parameters + +- `--model-id: string` + + Model identifier or alias. + +- `--beta: optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + +### Returns + +- `model_info: object { id, capabilities, created_at, 4 more }` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 2 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + +### Example + +```cli +ant models retrieve \ + --api-key my-anthropic-api-key \ + --model-id model_id +``` diff --git a/content/en/api/client-sdks.md b/content/en/api/client-sdks.md index feb822927..29d6c609f 100644 --- a/content/en/api/client-sdks.md +++ b/content/en/api/client-sdks.md @@ -1,12 +1,15 @@ # Client SDKs -Official SDKs for building with the Claude API in Python, TypeScript, Java, Go, Ruby, C#, and PHP. +Official SDKs for building with the Claude API in Python, TypeScript, Java, Go, Ruby, C#, PHP, and the command line. --- Anthropic provides official client SDKs in multiple languages to make it easier to work with the Claude API. Each SDK provides idiomatic interfaces, type safety, and built-in support for features like streaming, retries, and error handling. + + Shell scripting, typed flags, response transforms + Sync and async clients, Pydantic models @@ -33,6 +36,11 @@ Anthropic provides official client SDKs in multiple languages to make it easier ## Quick installation + +```bash +brew install anthropics/tap/ant +``` + ```bash pip install anthropic @@ -56,14 +64,14 @@ go get github.com/anthropics/anthropic-sdk-go ```groovy Gradle -implementation("com.anthropic:anthropic-java:2.18.0") +implementation("com.anthropic:anthropic-java:2.20.0") ``` ```xml Maven com.anthropic anthropic-java - 2.18.0 + 2.20.0 ``` @@ -83,6 +91,14 @@ bundler add anthropic ## Quick start +```bash CLI +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --message '{role: user, content: "Hello, Claude"}' \ + --transform content +``` + ```python Python import anthropic @@ -224,6 +240,14 @@ Access beta features using the `beta` namespace in any SDK: +```bash CLI nocheck +ant beta:messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --message '{role: user, content: "Hello"}' \ + --beta feature-name +``` + ```python Python nocheck message = client.beta.messages.create( model="claude-opus-4-6", diff --git a/content/en/api/completions.md b/content/en/api/completions.md index 25d48f90b..e530f7c9b 100644 --- a/content/en/api/completions.md +++ b/content/en/api/completions.md @@ -18,7 +18,7 @@ Future models and features will not be compatible with Text Completions. See our - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Future models and features will not be compatible with Text Completions. See our - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Body Parameters - `max_tokens_to_sample: number` @@ -78,15 +76,19 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -234,15 +236,19 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -329,7 +335,7 @@ curl https://api.anthropic.com/v1/complete \ --max-time 600 \ -d '{ "max_tokens_to_sample": 256, - "model": "claude-opus-4-6", + "model": "claude-mythos-preview", "prompt": "\\n\\nHuman: Hello, world!\\n\\nAssistant:" }' ``` @@ -356,15 +362,19 @@ curl https://api.anthropic.com/v1/complete \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/completions/create.md b/content/en/api/completions/create.md index deee11be4..24383a675 100644 --- a/content/en/api/completions/create.md +++ b/content/en/api/completions/create.md @@ -16,7 +16,7 @@ Future models and features will not be compatible with Text Completions. See our - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -60,8 +60,6 @@ Future models and features will not be compatible with Text Completions. See our - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Body Parameters - `max_tokens_to_sample: number` @@ -76,15 +74,19 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -232,15 +234,19 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -327,7 +333,7 @@ curl https://api.anthropic.com/v1/complete \ --max-time 600 \ -d '{ "max_tokens_to_sample": 256, - "model": "claude-opus-4-6", + "model": "claude-mythos-preview", "prompt": "\\n\\nHuman: Hello, world!\\n\\nAssistant:" }' ``` diff --git a/content/en/api/csharp/beta.md b/content/en/api/csharp/beta.md index 8836ef4da..0633e2e19 100644 --- a/content/en/api/csharp/beta.md +++ b/content/en/api/csharp/beta.md @@ -272,8 +272,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class ModelListPageResponse:` @@ -546,8 +544,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaModelInfo:` @@ -5061,10 +5057,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. - - `string? userProfileID` - - Body param: The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `IReadOnlyList betas` Header param: Optional header to specify the beta version(s) you want to use. @@ -5111,8 +5103,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessage:` @@ -5908,9 +5898,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -10014,8 +10008,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageTokensCount:` @@ -10045,7 +10037,7 @@ MessageCountTokensParams parameters = new() Role = Role.User, }, ], - Model = Model.ClaudeOpus4_6, + Model = Model.ClaudeMythosPreview, }; var betaMessageTokensCount = await client.Beta.Messages.CountTokens(parameters); @@ -16180,9 +16172,13 @@ Console.WriteLine(betaMessageTokensCount); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -20832,9 +20828,13 @@ Console.WriteLine(betaMessageTokensCount); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -21926,9 +21926,13 @@ Console.WriteLine(betaMessageTokensCount); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -31730,9 +31734,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -33613,10 +33621,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `string? UserProfileID` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `IReadOnlyList betas` Header param: Optional header to specify the beta version(s) you want to use. @@ -33663,8 +33667,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatch:` @@ -33921,7 +33923,6 @@ BatchCreateParams parameters = new() ], TopK = 5, TopP = 0.7, - UserProfileID = "user_profile_id", }, }, ], @@ -33996,8 +33997,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatch:` @@ -34170,8 +34169,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BatchListPageResponse:` @@ -34352,8 +34349,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatch:` @@ -34518,8 +34513,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaDeletedMessageBatch:` @@ -34610,8 +34603,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatchIndividualResponse:` @@ -35425,9 +35416,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -36796,9 +36791,13 @@ await foreach (var betaMessageBatchIndividualResponse in client.Beta.Messages.Ba See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -37994,9 +37993,13 @@ await foreach (var betaMessageBatchIndividualResponse in client.Beta.Messages.Ba See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -39154,9 +39157,13 @@ await foreach (var betaMessageBatchIndividualResponse in client.Beta.Messages.Ba See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -39443,23 +39450,373 @@ await foreach (var betaMessageBatchIndividualResponse in client.Beta.Messages.Ba - `JsonElement Type "succeeded"constant` -# Files +# Agents -## Upload +## Create -`FileMetadata Beta.Files.Upload(FileUploadParamsparameters, CancellationTokencancellationToken = default)` +`BetaManagedAgentsAgent Beta.Agents.Create(AgentCreateParamsparameters, CancellationTokencancellationToken = default)` -**post** `/v1/files` +**post** `/v1/agents` -Upload File +Create Agent ### Parameters -- `FileUploadParams parameters` +- `AgentCreateParams parameters` - - `required string file` + - `required Model model` - Body param: The file to upload + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `enum BetaManagedAgentsModel:` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `class BetaManagedAgentsModelConfigParams:` + + An object that defines additional configuration control over model use + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string name` + + Body param: Human-readable name for the agent. 1-256 characters. + + - `string? description` + + Body param: Description of what the agent does. Up to 2048 characters. + + - `IReadOnlyList mcpServers` + + Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `required string Name` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + Endpoint URL for the MCP server. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + + - `IReadOnlyList skills` + + Body param: Skills available to the agent. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams:` + + An Anthropic-managed skill. + + - `required string SkillID` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams:` + + A user-created custom skill. + + - `required string SkillID` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `required Type Type` + + - `"custom"Custom` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `string? system` + + Body param: System prompt for the agent. Up to 100,000 characters. + + - `IReadOnlyList tools` + + Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params:` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `Boolean? Enabled` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsAgentToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools in a toolset. + + - `Boolean? Enabled` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `class BetaManagedAgentsMcpToolsetParams:` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `required string McpServerName` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required string Name` + + Name of the MCP tool to configure. 1-128 characters. + + - `Boolean? Enabled` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsMcpToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools from an MCP server. + + - `Boolean? Enabled` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `class BetaManagedAgentsCustomToolParams:` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `required string Description` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `required Type Type` + + - `"custom"Custom` - `IReadOnlyList betas` @@ -39507,7 +39864,22020 @@ Upload File - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```csharp +AgentCreateParams parameters = new() +{ + Model = BetaManagedAgentsModel.ClaudeSonnet4_6, + Name = "My First Agent", +}; + +var betaManagedAgentsAgent = await client.Beta.Agents.Create(parameters); + +Console.WriteLine(betaManagedAgentsAgent); +``` + +## List + +`AgentListPageResponse Beta.Agents.List(AgentListParams?parameters, CancellationTokencancellationToken = default)` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `AgentListParams parameters` + + - `DateTimeOffset createdAtGte` + + Query param: Return agents created at or after this time (inclusive). + + - `DateTimeOffset createdAtLte` + + Query param: Return agents created at or before this time (inclusive). + + - `Boolean includeArchived` + + Query param: Include archived agents in results. Defaults to false. + + - `Int limit` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `string page` + + Query param: Opaque pagination cursor from a previous response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class AgentListPageResponse:` + + Paginated list of agents. + + - `IReadOnlyList Data` + + List of agents. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +AgentListParams parameters = new(); + +var page = await client.Beta.Agents.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`BetaManagedAgentsAgent Beta.Agents.Retrieve(AgentRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `AgentRetrieveParams parameters` + + - `required string agentID` + + Path param: Path parameter agent_id + + - `Int version` + + Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```csharp +AgentRetrieveParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP" +}; + +var betaManagedAgentsAgent = await client.Beta.Agents.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsAgent); +``` + +## Update + +`BetaManagedAgentsAgent Beta.Agents.Update(AgentUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `AgentUpdateParams parameters` + + - `required string agentID` + + Path param: Path parameter agent_id + + - `required Int version` + + Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + + - `string? description` + + Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + + - `IReadOnlyList? mcpServers` + + Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `required string Name` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + Endpoint URL for the MCP server. + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + + - `Model model` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `enum BetaManagedAgentsModel:` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `class BetaManagedAgentsModelConfigParams:` + + An object that defines additional configuration control over model use + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `string name` + + Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + + - `IReadOnlyList? skills` + + Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams:` + + An Anthropic-managed skill. + + - `required string SkillID` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams:` + + A user-created custom skill. + + - `required string SkillID` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `required Type Type` + + - `"custom"Custom` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `string? system` + + Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + + - `IReadOnlyList? tools` + + Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params:` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `Boolean? Enabled` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsAgentToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools in a toolset. + + - `Boolean? Enabled` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `class BetaManagedAgentsMcpToolsetParams:` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `required string McpServerName` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required string Name` + + Name of the MCP tool to configure. 1-128 characters. + + - `Boolean? Enabled` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsMcpToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools from an MCP server. + + - `Boolean? Enabled` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `class BetaManagedAgentsCustomToolParams:` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `required string Description` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `required Type Type` + + - `"custom"Custom` + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```csharp +AgentUpdateParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP", + Version = 1, +}; + +var betaManagedAgentsAgent = await client.Beta.Agents.Update(parameters); + +Console.WriteLine(betaManagedAgentsAgent); +``` + +## Archive + +`BetaManagedAgentsAgent Beta.Agents.Archive(AgentArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `AgentArchiveParams parameters` + + - `required string agentID` + + Path parameter agent_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```csharp +AgentArchiveParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP" +}; + +var betaManagedAgentsAgent = await client.Beta.Agents.Archive(parameters); + +Console.WriteLine(betaManagedAgentsAgent); +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `class BetaManagedAgentsAgentToolConfig:` + + Configuration for a specific agent tool. + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Agent Tool Config Params + +- `class BetaManagedAgentsAgentToolConfigParams:` + + Configuration override for a specific tool within a toolset. + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `Boolean? Enabled` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Agent Toolset Default Config + +- `class BetaManagedAgentsAgentToolsetDefaultConfig:` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `class BetaManagedAgentsAgentToolsetDefaultConfigParams:` + + Default configuration for all tools in a toolset. + + - `Boolean? Enabled` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Agent Toolset20260401 + +- `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `class BetaManagedAgentsAgentToolset20260401Params:` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `Boolean? Enabled` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsAgentToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools in a toolset. + + - `Boolean? Enabled` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Always Allow Policy + +- `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + +### Beta Managed Agents Always Ask Policy + +- `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Anthropic Skill + +- `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + +### Beta Managed Agents Anthropic Skill Params + +- `class BetaManagedAgentsAnthropicSkillParams:` + + An Anthropic-managed skill. + + - `required string SkillID` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + +### Beta Managed Agents Custom Skill Params + +- `class BetaManagedAgentsCustomSkillParams:` + + A user-created custom skill. + + - `required string SkillID` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `required Type Type` + + - `"custom"Custom` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + +### Beta Managed Agents Custom Tool Input Schema + +- `class BetaManagedAgentsCustomToolInputSchema:` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + +### Beta Managed Agents Custom Tool Params + +- `class BetaManagedAgentsCustomToolParams:` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `required string Description` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `required Type Type` + + - `"custom"Custom` + +### Beta Managed Agents MCP Server URL Definition + +- `class BetaManagedAgentsMcpServerUrlDefinition:` + + URL-based MCP server connection as returned in API responses. + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + +### Beta Managed Agents MCP Tool Config + +- `class BetaManagedAgentsMcpToolConfig:` + + Resolved configuration for a specific MCP tool. + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents MCP Tool Config Params + +- `class BetaManagedAgentsMcpToolConfigParams:` + + Configuration override for a specific MCP tool. + + - `required string Name` + + Name of the MCP tool to configure. 1-128 characters. + + - `Boolean? Enabled` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents MCP Toolset + +- `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + +### Beta Managed Agents MCP Toolset Default Config + +- `class BetaManagedAgentsMcpToolsetDefaultConfig:` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `class BetaManagedAgentsMcpToolsetDefaultConfigParams:` + + Default configuration for all tools from an MCP server. + + - `Boolean? Enabled` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents MCP Toolset Params + +- `class BetaManagedAgentsMcpToolsetParams:` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `required string McpServerName` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required string Name` + + Name of the MCP tool to configure. 1-128 characters. + + - `Boolean? Enabled` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsMcpToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools from an MCP server. + + - `Boolean? Enabled` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Model Config + +- `class BetaManagedAgentsModelConfig:` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + +### Beta Managed Agents Model Config Params + +- `class BetaManagedAgentsModelConfigParams:` + + An object that defines additional configuration control over model use + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + +### Beta Managed Agents Skill Params + +- `class BetaManagedAgentsSkillParams: A class that can be one of several variants.union` + + Skill to load in the session container. + + - `class BetaManagedAgentsAnthropicSkillParams:` + + An Anthropic-managed skill. + + - `required string SkillID` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams:` + + A user-created custom skill. + + - `required string SkillID` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `required Type Type` + + - `"custom"Custom` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `class BetaManagedAgentsUrlMcpServerParams:` + + URL-based MCP server connection. + + - `required string Name` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + Endpoint URL for the MCP server. + +# Versions + +## List + +`VersionListPageResponse Beta.Agents.Versions.List(VersionListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `VersionListParams parameters` + + - `required string agentID` + + Path param: Path parameter agent_id + + - `Int limit` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `string page` + + Query param: Opaque pagination cursor. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class VersionListPageResponse:` + + Paginated list of agent versions. + + - `IReadOnlyList Data` + + Agent versions. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +VersionListParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP" +}; + +var page = await client.Beta.Agents.Versions.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +# Environments + +## Create + +`BetaEnvironment Beta.Environments.Create(EnvironmentCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `EnvironmentCreateParams parameters` + + - `required string name` + + Body param: Human-readable name for the environment + + - `BetaCloudConfigParams? config` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `string? description` + + Body param: Optional description of the environment + + - `IReadOnlyDictionary metadata` + + Body param: User-provided metadata key-value pairs + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```csharp +EnvironmentCreateParams parameters = new() { Name = "python-data-analysis" }; + +var betaEnvironment = await client.Beta.Environments.Create(parameters); + +Console.WriteLine(betaEnvironment); +``` + +## List + +`EnvironmentListPageResponse Beta.Environments.List(EnvironmentListParams?parameters, CancellationTokencancellationToken = default)` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `EnvironmentListParams parameters` + + - `Boolean includeArchived` + + Query param: Include archived environments in the response + + - `Long limit` + + Query param: Maximum number of environments to return + + - `string? page` + + Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class EnvironmentListPageResponse:` + + Response when listing environments. + + This response model uses opaque cursor-based pagination. Use the `page` + query parameter with the value from `next_page` to fetch the next page. + + - `required IReadOnlyList Data` + + List of environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + + - `required string? NextPage` + + Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request. + +### Example + +```csharp +EnvironmentListParams parameters = new(); + +var page = await client.Beta.Environments.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`BetaEnvironment Beta.Environments.Retrieve(EnvironmentRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `EnvironmentRetrieveParams parameters` + + - `required string environmentID` + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```csharp +EnvironmentRetrieveParams parameters = new() +{ + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW" +}; + +var betaEnvironment = await client.Beta.Environments.Retrieve(parameters); + +Console.WriteLine(betaEnvironment); +``` + +## Update + +`BetaEnvironment Beta.Environments.Update(EnvironmentUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `EnvironmentUpdateParams parameters` + + - `required string environmentID` + + Path param + + - `BetaCloudConfigParams? config` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `string? description` + + Body param: Updated description of the environment + + - `IReadOnlyDictionary metadata` + + Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + + - `string? name` + + Body param: Updated name for the environment + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```csharp +EnvironmentUpdateParams parameters = new() +{ + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW" +}; + +var betaEnvironment = await client.Beta.Environments.Update(parameters); + +Console.WriteLine(betaEnvironment); +``` + +## Delete + +`BetaEnvironmentDeleteResponse Beta.Environments.Delete(EnvironmentDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `EnvironmentDeleteParams parameters` + + - `required string environmentID` + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironmentDeleteResponse:` + + Response after deleting an environment. + + - `required string ID` + + Environment identifier + + - `JsonElement Type "environment_deleted"constant` + + The type of response + +### Example + +```csharp +EnvironmentDeleteParams parameters = new() +{ + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW" +}; + +var betaEnvironmentDeleteResponse = await client.Beta.Environments.Delete(parameters); + +Console.WriteLine(betaEnvironmentDeleteResponse); +``` + +## Archive + +`BetaEnvironment Beta.Environments.Archive(EnvironmentArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `EnvironmentArchiveParams parameters` + + - `required string environmentID` + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```csharp +EnvironmentArchiveParams parameters = new() +{ + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW" +}; + +var betaEnvironment = await client.Beta.Environments.Archive(parameters); + +Console.WriteLine(betaEnvironment); +``` + +## Domain Types + +### Beta Cloud Config + +- `class BetaCloudConfig:` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + +### Beta Cloud Config Params + +- `class BetaCloudConfigParams:` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `JsonElement Type "cloud"constant` + + Environment type + + - `Networking? Networking` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetworkParams:` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `Boolean? AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `Boolean? AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `IReadOnlyList? AllowedHosts` + + Specifies domains the container can reach. + + - `BetaPackagesParams? Packages` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `IReadOnlyList? Apt` + + Ubuntu/Debian packages to install + + - `IReadOnlyList? Cargo` + + Rust packages to install + + - `IReadOnlyList? Gem` + + Ruby packages to install + + - `IReadOnlyList? Go` + + Go packages to install + + - `IReadOnlyList? Npm` + + Node.js packages to install + + - `IReadOnlyList? Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + +### Beta Environment + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `class BetaEnvironmentDeleteResponse:` + + Response after deleting an environment. + + - `required string ID` + + Environment identifier + + - `JsonElement Type "environment_deleted"constant` + + The type of response + +### Beta Limited Network + +- `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + +### Beta Limited Network Params + +- `class BetaLimitedNetworkParams:` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `Boolean? AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `Boolean? AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `IReadOnlyList? AllowedHosts` + + Specifies domains the container can reach. + +### Beta Packages + +- `class BetaPackages:` + + Packages (and their versions) available in this environment. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + +### Beta Packages Params + +- `class BetaPackagesParams:` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `IReadOnlyList? Apt` + + Ubuntu/Debian packages to install + + - `IReadOnlyList? Cargo` + + Rust packages to install + + - `IReadOnlyList? Gem` + + Ruby packages to install + + - `IReadOnlyList? Go` + + Go packages to install + + - `IReadOnlyList? Npm` + + Node.js packages to install + + - `IReadOnlyList? Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + +### Beta Unrestricted Network + +- `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + +# Sessions + +## Create + +`BetaManagedAgentsSession Beta.Sessions.Create(SessionCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `SessionCreateParams parameters` + + - `required Agent agent` + + Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `string` + + - `class BetaManagedAgentsAgentParams:` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `required string ID` + + The `agent` ID. + + - `required Type Type` + + - `"agent"Agent` + + - `Int Version` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + + - `required string environmentID` + + Body param: ID of the `environment` defining the container configuration for this session. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata attached to the session. + + - `IReadOnlyList resources` + + Body param: Resources (e.g. repositories, files) to mount into the session's container. + + - `class BetaManagedAgentsGitHubRepositoryResourceParams:` + + Mount a GitHub repository into the session's container. + + - `required string AuthorizationToken` + + GitHub authorization token used to clone the repository. + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required string Url` + + Github URL of the repository + + - `Checkout? Checkout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `string? MountPath` + + Mount path in the container. Defaults to `/workspace/`. + + - `class BetaManagedAgentsFileResourceParams:` + + Mount a file uploaded via the Files API into the session. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `string? MountPath` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `string? title` + + Body param: Human-readable session title. + + - `IReadOnlyList vaultIds` + + Body param: Vault IDs for stored credentials the agent can use during the session. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```csharp +SessionCreateParams parameters = new() +{ + Agent = "agent_011CZkYpogX7uDKUyvBTophP", + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW", +}; + +var betaManagedAgentsSession = await client.Beta.Sessions.Create(parameters); + +Console.WriteLine(betaManagedAgentsSession); +``` + +## List + +`SessionListPageResponse Beta.Sessions.List(SessionListParams?parameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `SessionListParams parameters` + + - `string agentID` + + Query param: Filter sessions created with this agent ID. + + - `Int agentVersion` + + Query param: Filter by agent version. Only applies when agent_id is also set. + + - `DateTimeOffset createdAtGt` + + Query param: Return sessions created after this time (exclusive). + + - `DateTimeOffset createdAtGte` + + Query param: Return sessions created at or after this time (inclusive). + + - `DateTimeOffset createdAtLt` + + Query param: Return sessions created before this time (exclusive). + + - `DateTimeOffset createdAtLte` + + Query param: Return sessions created at or before this time (inclusive). + + - `Boolean includeArchived` + + Query param: When true, includes archived sessions. Default: false (exclude archived). + + - `Int limit` + + Query param: Maximum number of results to return. + + - `Order order` + + Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `"asc"Asc` + + - `"desc"Desc` + + - `string page` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class SessionListPageResponse:` + + Paginated list of sessions. + + - `IReadOnlyList Data` + + List of sessions. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +SessionListParams parameters = new(); + +var page = await client.Beta.Sessions.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`BetaManagedAgentsSession Beta.Sessions.Retrieve(SessionRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `SessionRetrieveParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```csharp +SessionRetrieveParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var betaManagedAgentsSession = await client.Beta.Sessions.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsSession); +``` + +## Update + +`BetaManagedAgentsSession Beta.Sessions.Update(SessionUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `SessionUpdateParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + + - `string? title` + + Body param: Human-readable session title. + + - `IReadOnlyList vaultIds` + + Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```csharp +SessionUpdateParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var betaManagedAgentsSession = await client.Beta.Sessions.Update(parameters); + +Console.WriteLine(betaManagedAgentsSession); +``` + +## Delete + +`BetaManagedAgentsDeletedSession Beta.Sessions.Delete(SessionDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `SessionDeleteParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeletedSession:` + + Confirmation that a `session` has been permanently deleted. + + - `required string ID` + + - `required Type Type` + + - `"session_deleted"SessionDeleted` + +### Example + +```csharp +SessionDeleteParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var betaManagedAgentsDeletedSession = await client.Beta.Sessions.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeletedSession); +``` + +## Archive + +`BetaManagedAgentsSession Beta.Sessions.Archive(SessionArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `SessionArchiveParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```csharp +SessionArchiveParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var betaManagedAgentsSession = await client.Beta.Sessions.Archive(parameters); + +Console.WriteLine(betaManagedAgentsSession); +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `class BetaManagedAgentsAgentParams:` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `required string ID` + + The `agent` ID. + + - `required Type Type` + + - `"agent"Agent` + + - `Int Version` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + +### Beta Managed Agents Cache Creation Usage + +- `class BetaManagedAgentsCacheCreationUsage:` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + +### Beta Managed Agents Deleted Session + +- `class BetaManagedAgentsDeletedSession:` + + Confirmation that a `session` has been permanently deleted. + + - `required string ID` + + - `required Type Type` + + - `"session_deleted"SessionDeleted` + +### Beta Managed Agents File Resource Params + +- `class BetaManagedAgentsFileResourceParams:` + + Mount a file uploaded via the Files API into the session. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `string? MountPath` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `class BetaManagedAgentsGitHubRepositoryResourceParams:` + + Mount a GitHub repository into the session's container. + + - `required string AuthorizationToken` + + GitHub authorization token used to clone the repository. + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required string Url` + + Github URL of the repository + + - `Checkout? Checkout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `string? MountPath` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `class BetaManagedAgentsSessionAgent:` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + +### Beta Managed Agents Session Stats + +- `class BetaManagedAgentsSessionStats:` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `class BetaManagedAgentsSessionUsage:` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + +# Events + +## List + +`EventListPageResponse Beta.Sessions.Events.List(EventListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `EventListParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `Int limit` + + Query param: Query parameter for limit + + - `Order order` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"Asc` + + - `"desc"Desc` + + - `string page` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class EventListPageResponse:` + + Paginated list of events for a `session`. + + - `IReadOnlyList Data` + + Events for the session, ordered by `created_at`. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +EventListParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var page = await client.Beta.Sessions.Events.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Send + +`BetaManagedAgentsSendSessionEvents Beta.Sessions.Events.Send(EventSendParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `EventSendParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required IReadOnlyList events` + + Body param: Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `required IReadOnlyList Content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSendSessionEvents:` + + Events that were successfully sent to the session. + + - `IReadOnlyList Data` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +EventSendParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + Events = + [ + new BetaManagedAgentsUserMessageEventParams() + { + Content = + [ + new BetaManagedAgentsTextBlock() + { + Text = "Where is my order #1234?", + Type = Type.Text, + }, + ], + Type = Type.UserMessage, + }, + ], +}; + +var betaManagedAgentsSendSessionEvents = await client.Beta.Sessions.Events.Send(parameters); + +Console.WriteLine(betaManagedAgentsSendSessionEvents); +``` + +## Stream + +`BetaManagedAgentsStreamSessionEvents Beta.Sessions.Events.StreamStreaming(EventStreamParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `EventStreamParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Example + +```csharp +EventStreamParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +await foreach (var betaManagedAgentsStreamSessionEvents in client.Beta.Sessions.Events.StreamStreaming(parameters)) +{ + Console.WriteLine(betaManagedAgentsStreamSessionEvents); +} +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + +### Beta Managed Agents Agent Message Event + +- `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + +### Beta Managed Agents Agent Thinking Event + +- `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + +### Beta Managed Agents Agent Tool Result Event + +- `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + +### Beta Managed Agents Base64 Document Source + +- `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + +### Beta Managed Agents Base64 Image Source + +- `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + +### Beta Managed Agents Billing Error + +- `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + +### Beta Managed Agents Document Block + +- `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + +### Beta Managed Agents Event Params + +- `class BetaManagedAgentsEventParams: A class that can be one of several variants.union` + + Union type for event parameters that can be sent to a session. + + - `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `required IReadOnlyList Content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + +### Beta Managed Agents File Image Source + +- `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + +### Beta Managed Agents Image Block + +- `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + +### Beta Managed Agents MCP Authentication Failed Error + +- `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + +### Beta Managed Agents MCP Connection Failed Error + +- `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + +### Beta Managed Agents Model Overloaded Error + +- `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + +### Beta Managed Agents Model Rate Limited Error + +- `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + +### Beta Managed Agents Model Request Failed Error + +- `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + +### Beta Managed Agents Plain Text Document Source + +- `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + +### Beta Managed Agents Retry Status Exhausted + +- `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + +### Beta Managed Agents Retry Status Retrying + +- `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + +### Beta Managed Agents Retry Status Terminal + +- `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + +### Beta Managed Agents Send Session Events + +- `class BetaManagedAgentsSendSessionEvents:` + + Events that were successfully sent to the session. + + - `IReadOnlyList Data` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Beta Managed Agents Session End Turn + +- `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + +### Beta Managed Agents Session Error Event + +- `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + +### Beta Managed Agents Session Event + +- `class BetaManagedAgentsSessionEvent: A class that can be one of several variants.union` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Beta Managed Agents Session Requires Action + +- `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + +### Beta Managed Agents Session Retries Exhausted + +- `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + +### Beta Managed Agents Session Status Idle Event + +- `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + +### Beta Managed Agents Session Status Rescheduled Event + +- `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + +### Beta Managed Agents Session Status Running Event + +- `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + +### Beta Managed Agents Session Status Terminated Event + +- `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + +### Beta Managed Agents Span Model Request End Event + +- `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + +### Beta Managed Agents Span Model Request Start Event + +- `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + +### Beta Managed Agents Span Model Usage + +- `class BetaManagedAgentsSpanModelUsage:` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + +### Beta Managed Agents Stream Session Events + +- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Beta Managed Agents Text Block + +- `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + +### Beta Managed Agents Unknown Error + +- `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + +### Beta Managed Agents URL Document Source + +- `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + +### Beta Managed Agents User Message Event + +- `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `required IReadOnlyList Content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + +### Beta Managed Agents User Tool Confirmation Event + +- `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`BetaManagedAgentsFileResource Beta.Sessions.Resources.Add(ResourceAddParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `ResourceAddParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string fileID` + + Body param: ID of a previously uploaded file. + + - `required Type type` + + Body param + + - `"file"File` + + - `string? mountPath` + + Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +ResourceAddParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + FileID = "file_011CNha8iCJcU1wXNR6q4V8w", + Type = Type.File, +}; + +var betaManagedAgentsFileResource = await client.Beta.Sessions.Resources.Add(parameters); + +Console.WriteLine(betaManagedAgentsFileResource); +``` + +## List + +`ResourceListPageResponse Beta.Sessions.Resources.List(ResourceListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `ResourceListParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `Int limit` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `string page` + + Query param: Opaque cursor from a previous response's next_page field. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class ResourceListPageResponse:` + + Paginated list of resources attached to a session. + + - `required IReadOnlyList Data` + + Resources for the session, ordered by `created_at`. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +ResourceListParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var page = await client.Beta.Sessions.Resources.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`ResourceRetrieveResponse Beta.Sessions.Resources.Retrieve(ResourceRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `ResourceRetrieveParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string resourceID` + + Path param: Path parameter resource_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class ResourceRetrieveResponse: A class that can be one of several variants.union` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +ResourceRetrieveParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + ResourceID = "sesrsc_011CZkZBJq5dWxk9fVLNcPht", +}; + +var resource = await client.Beta.Sessions.Resources.Retrieve(parameters); + +Console.WriteLine(resource); +``` + +## Update + +`ResourceUpdateResponse Beta.Sessions.Resources.Update(ResourceUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `ResourceUpdateParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string resourceID` + + Path param: Path parameter resource_id + + - `required string authorizationToken` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class ResourceUpdateResponse: A class that can be one of several variants.union` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +ResourceUpdateParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + ResourceID = "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + AuthorizationToken = "ghp_exampletoken", +}; + +var resource = await client.Beta.Sessions.Resources.Update(parameters); + +Console.WriteLine(resource); +``` + +## Delete + +`BetaManagedAgentsDeleteSessionResource Beta.Sessions.Resources.Delete(ResourceDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `ResourceDeleteParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string resourceID` + + Path param: Path parameter resource_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource:` + + Confirmation of resource deletion. + + - `required string ID` + + - `required Type Type` + + - `"session_resource_deleted"SessionResourceDeleted` + +### Example + +```csharp +ResourceDeleteParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + ResourceID = "sesrsc_011CZkZBJq5dWxk9fVLNcPht", +}; + +var betaManagedAgentsDeleteSessionResource = await client.Beta.Sessions.Resources.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeleteSessionResource); +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `class BetaManagedAgentsDeleteSessionResource:` + + Confirmation of resource deletion. + + - `required string ID` + + - `required Type Type` + + - `"session_resource_deleted"SessionResourceDeleted` + +### Beta Managed Agents File Resource + +- `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + +### Beta Managed Agents Session Resource + +- `class BetaManagedAgentsSessionResource: A class that can be one of several variants.union` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +# Vaults + +## Create + +`BetaManagedAgentsVault Beta.Vaults.Create(VaultCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `VaultCreateParams parameters` + + - `required string displayName` + + Body param: Human-readable name for the vault. 1-255 characters. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata to attach to the vault. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +VaultCreateParams parameters = new() { DisplayName = "Example vault" }; + +var betaManagedAgentsVault = await client.Beta.Vaults.Create(parameters); + +Console.WriteLine(betaManagedAgentsVault); +``` + +## List + +`VaultListPageResponse Beta.Vaults.List(VaultListParams?parameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `VaultListParams parameters` + + - `Boolean includeArchived` + + Query param: Whether to include archived vaults in the results. + + - `Int limit` + + Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. + + - `string page` + + Query param: Opaque pagination token from a previous `list_vaults` response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class VaultListPageResponse:` + + Response containing a paginated list of vaults. + + - `IReadOnlyList Data` + + List of vaults. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `string? NextPage` + + Pagination token for the next page, or null if no more results. + +### Example + +```csharp +VaultListParams parameters = new(); + +var page = await client.Beta.Vaults.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`BetaManagedAgentsVault Beta.Vaults.Retrieve(VaultRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `VaultRetrieveParams parameters` + + - `required string vaultID` + + Path parameter vault_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +VaultRetrieveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var betaManagedAgentsVault = await client.Beta.Vaults.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsVault); +``` + +## Update + +`BetaManagedAgentsVault Beta.Vaults.Update(VaultUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `VaultUpdateParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `string? displayName` + + Body param: Updated human-readable name for the vault. 1-255 characters. + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +VaultUpdateParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var betaManagedAgentsVault = await client.Beta.Vaults.Update(parameters); + +Console.WriteLine(betaManagedAgentsVault); +``` + +## Delete + +`BetaManagedAgentsDeletedVault Beta.Vaults.Delete(VaultDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `VaultDeleteParams parameters` + + - `required string vaultID` + + Path parameter vault_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeletedVault:` + + Confirmation of a deleted vault. + + - `required string ID` + + Unique identifier of the deleted vault. + + - `required Type Type` + + - `"vault_deleted"VaultDeleted` + +### Example + +```csharp +VaultDeleteParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var betaManagedAgentsDeletedVault = await client.Beta.Vaults.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeletedVault); +``` + +## Archive + +`BetaManagedAgentsVault Beta.Vaults.Archive(VaultArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `VaultArchiveParams parameters` + + - `required string vaultID` + + Path parameter vault_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +VaultArchiveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var betaManagedAgentsVault = await client.Beta.Vaults.Archive(parameters); + +Console.WriteLine(betaManagedAgentsVault); +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `class BetaManagedAgentsDeletedVault:` + + Confirmation of a deleted vault. + + - `required string ID` + + Unique identifier of the deleted vault. + + - `required Type Type` + + - `"vault_deleted"VaultDeleted` + +### Beta Managed Agents Vault + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Create(CredentialCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `CredentialCreateParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required Auth auth` + + Body param: Authentication details for creating a credential. + + - `class BetaManagedAgentsMcpOAuthCreateParams:` + + Parameters for creating an MCP OAuth credential. + + - `required string AccessToken` + + OAuth access token. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshParams? Refresh` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `required string ClientID` + + OAuth client ID. + + - `required string RefreshToken` + + OAuth refresh token. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams:` + + Parameters for creating a static bearer token credential. + + - `required string Token` + + Static bearer token value. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `string? displayName` + + Body param: Human-readable name for the credential. Up to 255 characters. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata to attach to the credential. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialCreateParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + Auth = new BetaManagedAgentsStaticBearerCreateParams() + { + Token = "bearer_exampletoken", + McpServerUrl = "https://example-server.modelcontextprotocol.io/sse", + Type = Type.StaticBearer, + }, +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Create(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` + +## List + +`CredentialListPageResponse Beta.Vaults.Credentials.List(CredentialListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `CredentialListParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `Boolean includeArchived` + + Query param: Whether to include archived credentials in the results. + + - `Int limit` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `string page` + + Query param: Opaque pagination token from a previous `list_credentials` response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class CredentialListPageResponse:` + + Response containing a paginated list of credentials. + + - `IReadOnlyList Data` + + List of credentials. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + + - `string? NextPage` + + Pagination token for the next page, or null if no more results. + +### Example + +```csharp +CredentialListParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var page = await client.Beta.Vaults.Credentials.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Retrieve(CredentialRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `CredentialRetrieveParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialRetrieveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` + +## Update + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Update(CredentialUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `CredentialUpdateParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `Auth auth` + + Body param: Updated authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthUpdateParams:` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `string? AccessToken` + + Updated OAuth access token. + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshUpdateParams? Refresh` + + Parameters for updating OAuth refresh token configuration. + + - `string? RefreshToken` + + Updated OAuth refresh token. + + - `string? Scope` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth TokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams:` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `string? Token` + + Updated static bearer token value. + + - `string? displayName` + + Body param: Updated human-readable name for the credential. 1-255 characters. + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialUpdateParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Update(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` + +## Delete + +`BetaManagedAgentsDeletedCredential Beta.Vaults.Credentials.Delete(CredentialDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `CredentialDeleteParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeletedCredential:` + + Confirmation of a deleted credential. + + - `required string ID` + + Unique identifier of the deleted credential. + + - `required Type Type` + + - `"vault_credential_deleted"VaultCredentialDeleted` + +### Example + +```csharp +CredentialDeleteParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsDeletedCredential = await client.Beta.Vaults.Credentials.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeletedCredential); +``` + +## Archive + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Archive(CredentialArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `CredentialArchiveParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialArchiveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Archive(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `class BetaManagedAgentsDeletedCredential:` + + Confirmation of a deleted credential. + + - `required string ID` + + Unique identifier of the deleted credential. + + - `required Type Type` + + - `"vault_credential_deleted"VaultCredentialDeleted` + +### Beta Managed Agents MCP OAuth Auth Response + +- `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `class BetaManagedAgentsMcpOAuthCreateParams:` + + Parameters for creating an MCP OAuth credential. + + - `required string AccessToken` + + OAuth access token. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshParams? Refresh` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `required string ClientID` + + OAuth client ID. + + - `required string RefreshToken` + + OAuth refresh token. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `class BetaManagedAgentsMcpOAuthRefreshParams:` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `required string ClientID` + + OAuth client ID. + + - `required string RefreshToken` + + OAuth refresh token. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `class BetaManagedAgentsMcpOAuthRefreshResponse:` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `class BetaManagedAgentsMcpOAuthRefreshUpdateParams:` + + Parameters for updating OAuth refresh token configuration. + + - `string? RefreshToken` + + Updated OAuth refresh token. + + - `string? Scope` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth TokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `class BetaManagedAgentsMcpOAuthUpdateParams:` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `string? AccessToken` + + Updated OAuth access token. + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshUpdateParams? Refresh` + + Parameters for updating OAuth refresh token configuration. + + - `string? RefreshToken` + + Updated OAuth refresh token. + + - `string? Scope` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth TokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + +### Beta Managed Agents Static Bearer Create Params + +- `class BetaManagedAgentsStaticBearerCreateParams:` + + Parameters for creating a static bearer token credential. + + - `required string Token` + + Static bearer token value. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + +### Beta Managed Agents Static Bearer Update Params + +- `class BetaManagedAgentsStaticBearerUpdateParams:` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `string? Token` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. + +# Files + +## Upload + +`FileMetadata Beta.Files.Upload(FileUploadParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/files` + +Upload File + +### Parameters + +- `FileUploadParams parameters` + + - `required string file` + + Body param: The file to upload + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` ### Returns @@ -39545,6 +61915,18 @@ Upload File Whether the file can be downloaded. + - `BetaFileScope? Scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). + ### Example ```csharp @@ -39584,6 +61966,10 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. + - `string scopeID` + + Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `IReadOnlyList betas` Header param: Optional header to specify the beta version(s) you want to use. @@ -39630,8 +62016,6 @@ List Files - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class FileListPageResponse:` @@ -39672,6 +62056,18 @@ List Files Whether the file can be downloaded. + - `BetaFileScope? Scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). + - `string? FirstID` ID of the first file in this page of results. @@ -39758,8 +62154,6 @@ Download File - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Example ```csharp @@ -39832,8 +62226,6 @@ Get File Metadata - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class FileMetadata:` @@ -39870,6 +62262,18 @@ Get File Metadata Whether the file can be downloaded. + - `BetaFileScope? Scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). + ### Example ```csharp @@ -39942,8 +62346,6 @@ Delete File - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class DeletedFile:` @@ -39972,6 +62374,18 @@ Console.WriteLine(deletedFile); ## Domain Types +### Beta File Scope + +- `class BetaFileScope:` + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). + ### Deleted File - `class DeletedFile:` @@ -40024,6 +62438,18 @@ Console.WriteLine(deletedFile); Whether the file can be downloaded. + - `BetaFileScope? Scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). + # Skills ## Create @@ -40096,8 +62522,6 @@ Create Skill - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class SkillCreateResponse:` @@ -40232,8 +62656,6 @@ List Skills - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class SkillListPageResponse:` @@ -40371,8 +62793,6 @@ Get Skill - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class SkillRetrieveResponse:` @@ -40492,8 +62912,6 @@ Delete Skill - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class SkillDeleteResponse:` @@ -40592,8 +63010,6 @@ Create Skill Version - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionCreateResponse:` @@ -40726,8 +63142,6 @@ List Skill Versions - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionListPageResponse:` @@ -40870,8 +63284,6 @@ Get Skill Version - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionRetrieveResponse:` @@ -41004,8 +63416,6 @@ Delete Skill Version - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionDeleteResponse:` @@ -41035,557 +63445,3 @@ var version = await client.Beta.Skills.Versions.Delete(parameters); Console.WriteLine(version); ``` - -# User Profiles - -## Create - -`BetaUserProfile Beta.UserProfiles.Create(UserProfileCreateParams?parameters, CancellationTokencancellationToken = default)` - -**post** `/v1/user_profiles` - -Create User Profile - -### Parameters - -- `UserProfileCreateParams parameters` - - - `string? externalID` - - Body param - - - `IReadOnlyDictionary metadata` - - Body param: Free-form key-value data to attach to this user profile. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. Values must be non-empty strings. - - - `IReadOnlyList betas` - - Header param: Optional header to specify the beta version(s) you want to use. - - - `"message-batches-2024-09-24"MessageBatches2024_09_24` - - - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` - - - `"computer-use-2024-10-22"ComputerUse2024_10_22` - - - `"computer-use-2025-01-24"ComputerUse2025_01_24` - - - `"pdfs-2024-09-25"Pdfs2024_09_25` - - - `"token-counting-2024-11-01"TokenCounting2024_11_01` - - - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` - - - `"output-128k-2025-02-19"Output128k2025_02_19` - - - `"files-api-2025-04-14"FilesApi2025_04_14` - - - `"mcp-client-2025-04-04"McpClient2025_04_04` - - - `"mcp-client-2025-11-20"McpClient2025_11_20` - - - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` - - - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` - - - `"code-execution-2025-05-22"CodeExecution2025_05_22` - - - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` - - - `"context-1m-2025-08-07"Context1m2025_08_07` - - - `"context-management-2025-06-27"ContextManagement2025_06_27` - - - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` - - - `"skills-2025-10-02"Skills2025_10_02` - - - `"fast-mode-2026-02-01"FastMode2026_02_01` - - - `"output-300k-2026-03-24"Output300k2026_03_24` - - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - -### Returns - -- `class BetaUserProfile:` - - - `required string ID` - - - `required DateTimeOffset CreatedAt` - - A timestamp in RFC 3339 format - - - `required IReadOnlyDictionary Metadata` - - - `required IReadOnlyDictionary TrustGrants` - - - `required string Status` - - - `required string Type` - - - `required DateTimeOffset UpdatedAt` - - A timestamp in RFC 3339 format - - - `string? ExternalID` - -### Example - -```csharp -UserProfileCreateParams parameters = new(); - -var betaUserProfile = await client.Beta.UserProfiles.Create(parameters); - -Console.WriteLine(betaUserProfile); -``` - -## List - -`UserProfileListPageResponse Beta.UserProfiles.List(UserProfileListParams?parameters, CancellationTokencancellationToken = default)` - -**get** `/v1/user_profiles` - -List User Profiles - -### Parameters - -- `UserProfileListParams parameters` - - - `Int limit` - - Query param: Query parameter for limit - - - `Order order` - - Query param: Query parameter for order - - - `"asc"Asc` - - - `"desc"Desc` - - - `string page` - - Query param: Query parameter for page - - - `IReadOnlyList betas` - - Header param: Optional header to specify the beta version(s) you want to use. - - - `"message-batches-2024-09-24"MessageBatches2024_09_24` - - - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` - - - `"computer-use-2024-10-22"ComputerUse2024_10_22` - - - `"computer-use-2025-01-24"ComputerUse2025_01_24` - - - `"pdfs-2024-09-25"Pdfs2024_09_25` - - - `"token-counting-2024-11-01"TokenCounting2024_11_01` - - - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` - - - `"output-128k-2025-02-19"Output128k2025_02_19` - - - `"files-api-2025-04-14"FilesApi2025_04_14` - - - `"mcp-client-2025-04-04"McpClient2025_04_04` - - - `"mcp-client-2025-11-20"McpClient2025_11_20` - - - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` - - - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` - - - `"code-execution-2025-05-22"CodeExecution2025_05_22` - - - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` - - - `"context-1m-2025-08-07"Context1m2025_08_07` - - - `"context-management-2025-06-27"ContextManagement2025_06_27` - - - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` - - - `"skills-2025-10-02"Skills2025_10_02` - - - `"fast-mode-2026-02-01"FastMode2026_02_01` - - - `"output-300k-2026-03-24"Output300k2026_03_24` - - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - -### Returns - -- `class UserProfileListPageResponse:` - - - `required IReadOnlyList Data` - - - `required string ID` - - - `required DateTimeOffset CreatedAt` - - A timestamp in RFC 3339 format - - - `required IReadOnlyDictionary Metadata` - - - `required IReadOnlyDictionary TrustGrants` - - - `required string Status` - - - `required string Type` - - - `required DateTimeOffset UpdatedAt` - - A timestamp in RFC 3339 format - - - `string? ExternalID` - - - `string? NextPage` - -### Example - -```csharp -UserProfileListParams parameters = new(); - -var page = await client.Beta.UserProfiles.List(parameters); -await foreach (var item in page.Paginate()) -{ - Console.WriteLine(item); -} -``` - -## Retrieve - -`BetaUserProfile Beta.UserProfiles.Retrieve(UserProfileRetrieveParamsparameters, CancellationTokencancellationToken = default)` - -**get** `/v1/user_profiles/{id}` - -Get User Profile - -### Parameters - -- `UserProfileRetrieveParams parameters` - - - `required string id` - - Path parameter id - - - `IReadOnlyList betas` - - Optional header to specify the beta version(s) you want to use. - - - `"message-batches-2024-09-24"MessageBatches2024_09_24` - - - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` - - - `"computer-use-2024-10-22"ComputerUse2024_10_22` - - - `"computer-use-2025-01-24"ComputerUse2025_01_24` - - - `"pdfs-2024-09-25"Pdfs2024_09_25` - - - `"token-counting-2024-11-01"TokenCounting2024_11_01` - - - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` - - - `"output-128k-2025-02-19"Output128k2025_02_19` - - - `"files-api-2025-04-14"FilesApi2025_04_14` - - - `"mcp-client-2025-04-04"McpClient2025_04_04` - - - `"mcp-client-2025-11-20"McpClient2025_11_20` - - - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` - - - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` - - - `"code-execution-2025-05-22"CodeExecution2025_05_22` - - - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` - - - `"context-1m-2025-08-07"Context1m2025_08_07` - - - `"context-management-2025-06-27"ContextManagement2025_06_27` - - - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` - - - `"skills-2025-10-02"Skills2025_10_02` - - - `"fast-mode-2026-02-01"FastMode2026_02_01` - - - `"output-300k-2026-03-24"Output300k2026_03_24` - - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - -### Returns - -- `class BetaUserProfile:` - - - `required string ID` - - - `required DateTimeOffset CreatedAt` - - A timestamp in RFC 3339 format - - - `required IReadOnlyDictionary Metadata` - - - `required IReadOnlyDictionary TrustGrants` - - - `required string Status` - - - `required string Type` - - - `required DateTimeOffset UpdatedAt` - - A timestamp in RFC 3339 format - - - `string? ExternalID` - -### Example - -```csharp -UserProfileRetrieveParams parameters = new() { ID = "id" }; - -var betaUserProfile = await client.Beta.UserProfiles.Retrieve(parameters); - -Console.WriteLine(betaUserProfile); -``` - -## Update - -`BetaUserProfile Beta.UserProfiles.Update(UserProfileUpdateParamsparameters, CancellationTokencancellationToken = default)` - -**post** `/v1/user_profiles/{id}` - -Update User Profile - -### Parameters - -- `UserProfileUpdateParams parameters` - - - `required string id` - - Path param: Path parameter id - - - `string? externalID` - - Body param - - - `IReadOnlyDictionary metadata` - - Body param: Key-value pairs to merge into the stored metadata. Keys provided overwrite existing values. To remove a key, set its value to an empty string. Keys not provided are left unchanged. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. - - - `IReadOnlyList betas` - - Header param: Optional header to specify the beta version(s) you want to use. - - - `"message-batches-2024-09-24"MessageBatches2024_09_24` - - - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` - - - `"computer-use-2024-10-22"ComputerUse2024_10_22` - - - `"computer-use-2025-01-24"ComputerUse2025_01_24` - - - `"pdfs-2024-09-25"Pdfs2024_09_25` - - - `"token-counting-2024-11-01"TokenCounting2024_11_01` - - - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` - - - `"output-128k-2025-02-19"Output128k2025_02_19` - - - `"files-api-2025-04-14"FilesApi2025_04_14` - - - `"mcp-client-2025-04-04"McpClient2025_04_04` - - - `"mcp-client-2025-11-20"McpClient2025_11_20` - - - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` - - - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` - - - `"code-execution-2025-05-22"CodeExecution2025_05_22` - - - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` - - - `"context-1m-2025-08-07"Context1m2025_08_07` - - - `"context-management-2025-06-27"ContextManagement2025_06_27` - - - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` - - - `"skills-2025-10-02"Skills2025_10_02` - - - `"fast-mode-2026-02-01"FastMode2026_02_01` - - - `"output-300k-2026-03-24"Output300k2026_03_24` - - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - -### Returns - -- `class BetaUserProfile:` - - - `required string ID` - - - `required DateTimeOffset CreatedAt` - - A timestamp in RFC 3339 format - - - `required IReadOnlyDictionary Metadata` - - - `required IReadOnlyDictionary TrustGrants` - - - `required string Status` - - - `required string Type` - - - `required DateTimeOffset UpdatedAt` - - A timestamp in RFC 3339 format - - - `string? ExternalID` - -### Example - -```csharp -UserProfileUpdateParams parameters = new() { ID = "id" }; - -var betaUserProfile = await client.Beta.UserProfiles.Update(parameters); - -Console.WriteLine(betaUserProfile); -``` - -## Create Enrollment URL - -`BetaUserProfileEnrollmentUrl Beta.UserProfiles.CreateEnrollmentUrl(UserProfileCreateEnrollmentUrlParamsparameters, CancellationTokencancellationToken = default)` - -**post** `/v1/user_profiles/{id}/enrollment_url` - -Create Enrollment URL - -### Parameters - -- `UserProfileCreateEnrollmentUrlParams parameters` - - - `required string id` - - Path parameter id - - - `IReadOnlyList betas` - - Optional header to specify the beta version(s) you want to use. - - - `"message-batches-2024-09-24"MessageBatches2024_09_24` - - - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` - - - `"computer-use-2024-10-22"ComputerUse2024_10_22` - - - `"computer-use-2025-01-24"ComputerUse2025_01_24` - - - `"pdfs-2024-09-25"Pdfs2024_09_25` - - - `"token-counting-2024-11-01"TokenCounting2024_11_01` - - - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` - - - `"output-128k-2025-02-19"Output128k2025_02_19` - - - `"files-api-2025-04-14"FilesApi2025_04_14` - - - `"mcp-client-2025-04-04"McpClient2025_04_04` - - - `"mcp-client-2025-11-20"McpClient2025_11_20` - - - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` - - - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` - - - `"code-execution-2025-05-22"CodeExecution2025_05_22` - - - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` - - - `"context-1m-2025-08-07"Context1m2025_08_07` - - - `"context-management-2025-06-27"ContextManagement2025_06_27` - - - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` - - - `"skills-2025-10-02"Skills2025_10_02` - - - `"fast-mode-2026-02-01"FastMode2026_02_01` - - - `"output-300k-2026-03-24"Output300k2026_03_24` - - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - -### Returns - -- `class BetaUserProfileEnrollmentUrl:` - - - `required DateTimeOffset ExpiresAt` - - A timestamp in RFC 3339 format - - - `required string Type` - - - `required string Url` - -### Example - -```csharp -UserProfileCreateEnrollmentUrlParams parameters = new() { ID = "id" }; - -var betaUserProfileEnrollmentUrl = await client.Beta.UserProfiles.CreateEnrollmentUrl(parameters); - -Console.WriteLine(betaUserProfileEnrollmentUrl); -``` - -## Domain Types - -### Beta User Profile - -- `class BetaUserProfile:` - - - `required string ID` - - - `required DateTimeOffset CreatedAt` - - A timestamp in RFC 3339 format - - - `required IReadOnlyDictionary Metadata` - - - `required IReadOnlyDictionary TrustGrants` - - - `required string Status` - - - `required string Type` - - - `required DateTimeOffset UpdatedAt` - - A timestamp in RFC 3339 format - - - `string? ExternalID` - -### Beta User Profile Enrollment URL - -- `class BetaUserProfileEnrollmentUrl:` - - - `required DateTimeOffset ExpiresAt` - - A timestamp in RFC 3339 format - - - `required string Type` - - - `required string Url` - -### Beta User Profile Trust Grant - -- `class BetaUserProfileTrustGrant:` - - - `required string Status` diff --git a/content/en/api/csharp/beta/agents.md b/content/en/api/csharp/beta/agents.md new file mode 100644 index 000000000..c93cc1805 --- /dev/null +++ b/content/en/api/csharp/beta/agents.md @@ -0,0 +1,4164 @@ +# Agents + +## Create + +`BetaManagedAgentsAgent Beta.Agents.Create(AgentCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `AgentCreateParams parameters` + + - `required Model model` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `enum BetaManagedAgentsModel:` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `class BetaManagedAgentsModelConfigParams:` + + An object that defines additional configuration control over model use + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string name` + + Body param: Human-readable name for the agent. 1-256 characters. + + - `string? description` + + Body param: Description of what the agent does. Up to 2048 characters. + + - `IReadOnlyList mcpServers` + + Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `required string Name` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + Endpoint URL for the MCP server. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + + - `IReadOnlyList skills` + + Body param: Skills available to the agent. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams:` + + An Anthropic-managed skill. + + - `required string SkillID` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams:` + + A user-created custom skill. + + - `required string SkillID` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `required Type Type` + + - `"custom"Custom` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `string? system` + + Body param: System prompt for the agent. Up to 100,000 characters. + + - `IReadOnlyList tools` + + Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params:` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `Boolean? Enabled` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsAgentToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools in a toolset. + + - `Boolean? Enabled` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `class BetaManagedAgentsMcpToolsetParams:` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `required string McpServerName` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required string Name` + + Name of the MCP tool to configure. 1-128 characters. + + - `Boolean? Enabled` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsMcpToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools from an MCP server. + + - `Boolean? Enabled` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `class BetaManagedAgentsCustomToolParams:` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `required string Description` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `required Type Type` + + - `"custom"Custom` + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```csharp +AgentCreateParams parameters = new() +{ + Model = BetaManagedAgentsModel.ClaudeSonnet4_6, + Name = "My First Agent", +}; + +var betaManagedAgentsAgent = await client.Beta.Agents.Create(parameters); + +Console.WriteLine(betaManagedAgentsAgent); +``` + +## List + +`AgentListPageResponse Beta.Agents.List(AgentListParams?parameters, CancellationTokencancellationToken = default)` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `AgentListParams parameters` + + - `DateTimeOffset createdAtGte` + + Query param: Return agents created at or after this time (inclusive). + + - `DateTimeOffset createdAtLte` + + Query param: Return agents created at or before this time (inclusive). + + - `Boolean includeArchived` + + Query param: Include archived agents in results. Defaults to false. + + - `Int limit` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `string page` + + Query param: Opaque pagination cursor from a previous response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class AgentListPageResponse:` + + Paginated list of agents. + + - `IReadOnlyList Data` + + List of agents. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +AgentListParams parameters = new(); + +var page = await client.Beta.Agents.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`BetaManagedAgentsAgent Beta.Agents.Retrieve(AgentRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `AgentRetrieveParams parameters` + + - `required string agentID` + + Path param: Path parameter agent_id + + - `Int version` + + Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```csharp +AgentRetrieveParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP" +}; + +var betaManagedAgentsAgent = await client.Beta.Agents.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsAgent); +``` + +## Update + +`BetaManagedAgentsAgent Beta.Agents.Update(AgentUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `AgentUpdateParams parameters` + + - `required string agentID` + + Path param: Path parameter agent_id + + - `required Int version` + + Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + + - `string? description` + + Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + + - `IReadOnlyList? mcpServers` + + Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `required string Name` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + Endpoint URL for the MCP server. + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + + - `Model model` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `enum BetaManagedAgentsModel:` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `class BetaManagedAgentsModelConfigParams:` + + An object that defines additional configuration control over model use + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `string name` + + Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + + - `IReadOnlyList? skills` + + Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams:` + + An Anthropic-managed skill. + + - `required string SkillID` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams:` + + A user-created custom skill. + + - `required string SkillID` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `required Type Type` + + - `"custom"Custom` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `string? system` + + Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + + - `IReadOnlyList? tools` + + Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params:` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `Boolean? Enabled` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsAgentToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools in a toolset. + + - `Boolean? Enabled` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `class BetaManagedAgentsMcpToolsetParams:` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `required string McpServerName` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required string Name` + + Name of the MCP tool to configure. 1-128 characters. + + - `Boolean? Enabled` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsMcpToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools from an MCP server. + + - `Boolean? Enabled` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `class BetaManagedAgentsCustomToolParams:` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `required string Description` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `required Type Type` + + - `"custom"Custom` + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```csharp +AgentUpdateParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP", + Version = 1, +}; + +var betaManagedAgentsAgent = await client.Beta.Agents.Update(parameters); + +Console.WriteLine(betaManagedAgentsAgent); +``` + +## Archive + +`BetaManagedAgentsAgent Beta.Agents.Archive(AgentArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `AgentArchiveParams parameters` + + - `required string agentID` + + Path parameter agent_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```csharp +AgentArchiveParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP" +}; + +var betaManagedAgentsAgent = await client.Beta.Agents.Archive(parameters); + +Console.WriteLine(betaManagedAgentsAgent); +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `class BetaManagedAgentsAgentToolConfig:` + + Configuration for a specific agent tool. + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Agent Tool Config Params + +- `class BetaManagedAgentsAgentToolConfigParams:` + + Configuration override for a specific tool within a toolset. + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `Boolean? Enabled` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Agent Toolset Default Config + +- `class BetaManagedAgentsAgentToolsetDefaultConfig:` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `class BetaManagedAgentsAgentToolsetDefaultConfigParams:` + + Default configuration for all tools in a toolset. + + - `Boolean? Enabled` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Agent Toolset20260401 + +- `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `class BetaManagedAgentsAgentToolset20260401Params:` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `Boolean? Enabled` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsAgentToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools in a toolset. + + - `Boolean? Enabled` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Always Allow Policy + +- `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + +### Beta Managed Agents Always Ask Policy + +- `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Anthropic Skill + +- `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + +### Beta Managed Agents Anthropic Skill Params + +- `class BetaManagedAgentsAnthropicSkillParams:` + + An Anthropic-managed skill. + + - `required string SkillID` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + +### Beta Managed Agents Custom Skill Params + +- `class BetaManagedAgentsCustomSkillParams:` + + A user-created custom skill. + + - `required string SkillID` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `required Type Type` + + - `"custom"Custom` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + +### Beta Managed Agents Custom Tool Input Schema + +- `class BetaManagedAgentsCustomToolInputSchema:` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + +### Beta Managed Agents Custom Tool Params + +- `class BetaManagedAgentsCustomToolParams:` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `required string Description` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `required Type Type` + + - `"custom"Custom` + +### Beta Managed Agents MCP Server URL Definition + +- `class BetaManagedAgentsMcpServerUrlDefinition:` + + URL-based MCP server connection as returned in API responses. + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + +### Beta Managed Agents MCP Tool Config + +- `class BetaManagedAgentsMcpToolConfig:` + + Resolved configuration for a specific MCP tool. + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents MCP Tool Config Params + +- `class BetaManagedAgentsMcpToolConfigParams:` + + Configuration override for a specific MCP tool. + + - `required string Name` + + Name of the MCP tool to configure. 1-128 characters. + + - `Boolean? Enabled` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents MCP Toolset + +- `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + +### Beta Managed Agents MCP Toolset Default Config + +- `class BetaManagedAgentsMcpToolsetDefaultConfig:` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `class BetaManagedAgentsMcpToolsetDefaultConfigParams:` + + Default configuration for all tools from an MCP server. + + - `Boolean? Enabled` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents MCP Toolset Params + +- `class BetaManagedAgentsMcpToolsetParams:` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `required string McpServerName` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required string Name` + + Name of the MCP tool to configure. 1-128 characters. + + - `Boolean? Enabled` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsMcpToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools from an MCP server. + + - `Boolean? Enabled` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + +### Beta Managed Agents Model Config + +- `class BetaManagedAgentsModelConfig:` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + +### Beta Managed Agents Model Config Params + +- `class BetaManagedAgentsModelConfigParams:` + + An object that defines additional configuration control over model use + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + +### Beta Managed Agents Skill Params + +- `class BetaManagedAgentsSkillParams: A class that can be one of several variants.union` + + Skill to load in the session container. + + - `class BetaManagedAgentsAnthropicSkillParams:` + + An Anthropic-managed skill. + + - `required string SkillID` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams:` + + A user-created custom skill. + + - `required string SkillID` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `required Type Type` + + - `"custom"Custom` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `class BetaManagedAgentsUrlMcpServerParams:` + + URL-based MCP server connection. + + - `required string Name` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + Endpoint URL for the MCP server. + +# Versions + +## List + +`VersionListPageResponse Beta.Agents.Versions.List(VersionListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `VersionListParams parameters` + + - `required string agentID` + + Path param: Path parameter agent_id + + - `Int limit` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `string page` + + Query param: Opaque pagination cursor. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class VersionListPageResponse:` + + Paginated list of agent versions. + + - `IReadOnlyList Data` + + Agent versions. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +VersionListParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP" +}; + +var page = await client.Beta.Agents.Versions.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` diff --git a/content/en/api/csharp/beta/agents/archive.md b/content/en/api/csharp/beta/agents/archive.md new file mode 100644 index 000000000..f8bcfb89b --- /dev/null +++ b/content/en/api/csharp/beta/agents/archive.md @@ -0,0 +1,364 @@ +## Archive + +`BetaManagedAgentsAgent Beta.Agents.Archive(AgentArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `AgentArchiveParams parameters` + + - `required string agentID` + + Path parameter agent_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```csharp +AgentArchiveParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP" +}; + +var betaManagedAgentsAgent = await client.Beta.Agents.Archive(parameters); + +Console.WriteLine(betaManagedAgentsAgent); +``` diff --git a/content/en/api/csharp/beta/agents/create.md b/content/en/api/csharp/beta/agents/create.md new file mode 100644 index 000000000..86e638b97 --- /dev/null +++ b/content/en/api/csharp/beta/agents/create.md @@ -0,0 +1,715 @@ +## Create + +`BetaManagedAgentsAgent Beta.Agents.Create(AgentCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `AgentCreateParams parameters` + + - `required Model model` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `enum BetaManagedAgentsModel:` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `class BetaManagedAgentsModelConfigParams:` + + An object that defines additional configuration control over model use + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string name` + + Body param: Human-readable name for the agent. 1-256 characters. + + - `string? description` + + Body param: Description of what the agent does. Up to 2048 characters. + + - `IReadOnlyList mcpServers` + + Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `required string Name` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + Endpoint URL for the MCP server. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + + - `IReadOnlyList skills` + + Body param: Skills available to the agent. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams:` + + An Anthropic-managed skill. + + - `required string SkillID` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams:` + + A user-created custom skill. + + - `required string SkillID` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `required Type Type` + + - `"custom"Custom` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `string? system` + + Body param: System prompt for the agent. Up to 100,000 characters. + + - `IReadOnlyList tools` + + Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params:` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `Boolean? Enabled` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsAgentToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools in a toolset. + + - `Boolean? Enabled` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `class BetaManagedAgentsMcpToolsetParams:` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `required string McpServerName` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required string Name` + + Name of the MCP tool to configure. 1-128 characters. + + - `Boolean? Enabled` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsMcpToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools from an MCP server. + + - `Boolean? Enabled` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `class BetaManagedAgentsCustomToolParams:` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `required string Description` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `required Type Type` + + - `"custom"Custom` + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```csharp +AgentCreateParams parameters = new() +{ + Model = BetaManagedAgentsModel.ClaudeSonnet4_6, + Name = "My First Agent", +}; + +var betaManagedAgentsAgent = await client.Beta.Agents.Create(parameters); + +Console.WriteLine(betaManagedAgentsAgent); +``` diff --git a/content/en/api/csharp/beta/agents/list.md b/content/en/api/csharp/beta/agents/list.md new file mode 100644 index 000000000..4fa931c6b --- /dev/null +++ b/content/en/api/csharp/beta/agents/list.md @@ -0,0 +1,387 @@ +## List + +`AgentListPageResponse Beta.Agents.List(AgentListParams?parameters, CancellationTokencancellationToken = default)` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `AgentListParams parameters` + + - `DateTimeOffset createdAtGte` + + Query param: Return agents created at or after this time (inclusive). + + - `DateTimeOffset createdAtLte` + + Query param: Return agents created at or before this time (inclusive). + + - `Boolean includeArchived` + + Query param: Include archived agents in results. Defaults to false. + + - `Int limit` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `string page` + + Query param: Opaque pagination cursor from a previous response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class AgentListPageResponse:` + + Paginated list of agents. + + - `IReadOnlyList Data` + + List of agents. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +AgentListParams parameters = new(); + +var page = await client.Beta.Agents.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` diff --git a/content/en/api/csharp/beta/agents/retrieve.md b/content/en/api/csharp/beta/agents/retrieve.md new file mode 100644 index 000000000..aadfa34b4 --- /dev/null +++ b/content/en/api/csharp/beta/agents/retrieve.md @@ -0,0 +1,368 @@ +## Retrieve + +`BetaManagedAgentsAgent Beta.Agents.Retrieve(AgentRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `AgentRetrieveParams parameters` + + - `required string agentID` + + Path param: Path parameter agent_id + + - `Int version` + + Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```csharp +AgentRetrieveParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP" +}; + +var betaManagedAgentsAgent = await client.Beta.Agents.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsAgent); +``` diff --git a/content/en/api/csharp/beta/agents/update.md b/content/en/api/csharp/beta/agents/update.md new file mode 100644 index 000000000..11f43427c --- /dev/null +++ b/content/en/api/csharp/beta/agents/update.md @@ -0,0 +1,723 @@ +## Update + +`BetaManagedAgentsAgent Beta.Agents.Update(AgentUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `AgentUpdateParams parameters` + + - `required string agentID` + + Path param: Path parameter agent_id + + - `required Int version` + + Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + + - `string? description` + + Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + + - `IReadOnlyList? mcpServers` + + Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `required string Name` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + Endpoint URL for the MCP server. + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + + - `Model model` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `enum BetaManagedAgentsModel:` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `class BetaManagedAgentsModelConfigParams:` + + An object that defines additional configuration control over model use + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `string name` + + Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + + - `IReadOnlyList? skills` + + Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams:` + + An Anthropic-managed skill. + + - `required string SkillID` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams:` + + A user-created custom skill. + + - `required string SkillID` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `required Type Type` + + - `"custom"Custom` + + - `string? Version` + + Version to pin. Defaults to latest if omitted. + + - `string? system` + + Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + + - `IReadOnlyList? tools` + + Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params:` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `Boolean? Enabled` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsAgentToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools in a toolset. + + - `Boolean? Enabled` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `class BetaManagedAgentsMcpToolsetParams:` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `required string McpServerName` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `IReadOnlyList Configs` + + Per-tool configuration overrides. + + - `required string Name` + + Name of the MCP tool to configure. 1-128 characters. + + - `Boolean? Enabled` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `BetaManagedAgentsMcpToolsetDefaultConfigParams? DefaultConfig` + + Default configuration for all tools from an MCP server. + + - `Boolean? Enabled` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy? PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `class BetaManagedAgentsCustomToolParams:` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `required string Description` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `required Type Type` + + - `"custom"Custom` + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```csharp +AgentUpdateParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP", + Version = 1, +}; + +var betaManagedAgentsAgent = await client.Beta.Agents.Update(parameters); + +Console.WriteLine(betaManagedAgentsAgent); +``` diff --git a/content/en/api/csharp/beta/agents/versions.md b/content/en/api/csharp/beta/agents/versions.md new file mode 100644 index 000000000..348f212e5 --- /dev/null +++ b/content/en/api/csharp/beta/agents/versions.md @@ -0,0 +1,384 @@ +# Versions + +## List + +`VersionListPageResponse Beta.Agents.Versions.List(VersionListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `VersionListParams parameters` + + - `required string agentID` + + Path param: Path parameter agent_id + + - `Int limit` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `string page` + + Query param: Opaque pagination cursor. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class VersionListPageResponse:` + + Paginated list of agent versions. + + - `IReadOnlyList Data` + + Agent versions. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +VersionListParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP" +}; + +var page = await client.Beta.Agents.Versions.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` diff --git a/content/en/api/csharp/beta/agents/versions/list.md b/content/en/api/csharp/beta/agents/versions/list.md new file mode 100644 index 000000000..fa8480ccd --- /dev/null +++ b/content/en/api/csharp/beta/agents/versions/list.md @@ -0,0 +1,382 @@ +## List + +`VersionListPageResponse Beta.Agents.Versions.List(VersionListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `VersionListParams parameters` + + - `required string agentID` + + Path param: Path parameter agent_id + + - `Int limit` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `string page` + + Query param: Opaque pagination cursor. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class VersionListPageResponse:` + + Paginated list of agent versions. + + - `IReadOnlyList Data` + + Agent versions. + + - `required string ID` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required IReadOnlyDictionary Metadata` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required Int Version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +VersionListParams parameters = new() +{ + AgentID = "agent_011CZkYpogX7uDKUyvBTophP" +}; + +var page = await client.Beta.Agents.Versions.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` diff --git a/content/en/api/csharp/beta/environments.md b/content/en/api/csharp/beta/environments.md new file mode 100644 index 000000000..5e16291f2 --- /dev/null +++ b/content/en/api/csharp/beta/environments.md @@ -0,0 +1,1487 @@ +# Environments + +## Create + +`BetaEnvironment Beta.Environments.Create(EnvironmentCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `EnvironmentCreateParams parameters` + + - `required string name` + + Body param: Human-readable name for the environment + + - `BetaCloudConfigParams? config` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `string? description` + + Body param: Optional description of the environment + + - `IReadOnlyDictionary metadata` + + Body param: User-provided metadata key-value pairs + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```csharp +EnvironmentCreateParams parameters = new() { Name = "python-data-analysis" }; + +var betaEnvironment = await client.Beta.Environments.Create(parameters); + +Console.WriteLine(betaEnvironment); +``` + +## List + +`EnvironmentListPageResponse Beta.Environments.List(EnvironmentListParams?parameters, CancellationTokencancellationToken = default)` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `EnvironmentListParams parameters` + + - `Boolean includeArchived` + + Query param: Include archived environments in the response + + - `Long limit` + + Query param: Maximum number of environments to return + + - `string? page` + + Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class EnvironmentListPageResponse:` + + Response when listing environments. + + This response model uses opaque cursor-based pagination. Use the `page` + query parameter with the value from `next_page` to fetch the next page. + + - `required IReadOnlyList Data` + + List of environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + + - `required string? NextPage` + + Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request. + +### Example + +```csharp +EnvironmentListParams parameters = new(); + +var page = await client.Beta.Environments.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`BetaEnvironment Beta.Environments.Retrieve(EnvironmentRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `EnvironmentRetrieveParams parameters` + + - `required string environmentID` + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```csharp +EnvironmentRetrieveParams parameters = new() +{ + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW" +}; + +var betaEnvironment = await client.Beta.Environments.Retrieve(parameters); + +Console.WriteLine(betaEnvironment); +``` + +## Update + +`BetaEnvironment Beta.Environments.Update(EnvironmentUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `EnvironmentUpdateParams parameters` + + - `required string environmentID` + + Path param + + - `BetaCloudConfigParams? config` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `string? description` + + Body param: Updated description of the environment + + - `IReadOnlyDictionary metadata` + + Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + + - `string? name` + + Body param: Updated name for the environment + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```csharp +EnvironmentUpdateParams parameters = new() +{ + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW" +}; + +var betaEnvironment = await client.Beta.Environments.Update(parameters); + +Console.WriteLine(betaEnvironment); +``` + +## Delete + +`BetaEnvironmentDeleteResponse Beta.Environments.Delete(EnvironmentDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `EnvironmentDeleteParams parameters` + + - `required string environmentID` + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironmentDeleteResponse:` + + Response after deleting an environment. + + - `required string ID` + + Environment identifier + + - `JsonElement Type "environment_deleted"constant` + + The type of response + +### Example + +```csharp +EnvironmentDeleteParams parameters = new() +{ + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW" +}; + +var betaEnvironmentDeleteResponse = await client.Beta.Environments.Delete(parameters); + +Console.WriteLine(betaEnvironmentDeleteResponse); +``` + +## Archive + +`BetaEnvironment Beta.Environments.Archive(EnvironmentArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `EnvironmentArchiveParams parameters` + + - `required string environmentID` + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```csharp +EnvironmentArchiveParams parameters = new() +{ + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW" +}; + +var betaEnvironment = await client.Beta.Environments.Archive(parameters); + +Console.WriteLine(betaEnvironment); +``` + +## Domain Types + +### Beta Cloud Config + +- `class BetaCloudConfig:` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + +### Beta Cloud Config Params + +- `class BetaCloudConfigParams:` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `JsonElement Type "cloud"constant` + + Environment type + + - `Networking? Networking` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetworkParams:` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `Boolean? AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `Boolean? AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `IReadOnlyList? AllowedHosts` + + Specifies domains the container can reach. + + - `BetaPackagesParams? Packages` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `IReadOnlyList? Apt` + + Ubuntu/Debian packages to install + + - `IReadOnlyList? Cargo` + + Rust packages to install + + - `IReadOnlyList? Gem` + + Ruby packages to install + + - `IReadOnlyList? Go` + + Go packages to install + + - `IReadOnlyList? Npm` + + Node.js packages to install + + - `IReadOnlyList? Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + +### Beta Environment + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `class BetaEnvironmentDeleteResponse:` + + Response after deleting an environment. + + - `required string ID` + + Environment identifier + + - `JsonElement Type "environment_deleted"constant` + + The type of response + +### Beta Limited Network + +- `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + +### Beta Limited Network Params + +- `class BetaLimitedNetworkParams:` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `Boolean? AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `Boolean? AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `IReadOnlyList? AllowedHosts` + + Specifies domains the container can reach. + +### Beta Packages + +- `class BetaPackages:` + + Packages (and their versions) available in this environment. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + +### Beta Packages Params + +- `class BetaPackagesParams:` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `IReadOnlyList? Apt` + + Ubuntu/Debian packages to install + + - `IReadOnlyList? Cargo` + + Rust packages to install + + - `IReadOnlyList? Gem` + + Ruby packages to install + + - `IReadOnlyList? Go` + + Go packages to install + + - `IReadOnlyList? Npm` + + Node.js packages to install + + - `IReadOnlyList? Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + +### Beta Unrestricted Network + +- `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type diff --git a/content/en/api/csharp/beta/environments/archive.md b/content/en/api/csharp/beta/environments/archive.md new file mode 100644 index 000000000..f77d17754 --- /dev/null +++ b/content/en/api/csharp/beta/environments/archive.md @@ -0,0 +1,184 @@ +## Archive + +`BetaEnvironment Beta.Environments.Archive(EnvironmentArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `EnvironmentArchiveParams parameters` + + - `required string environmentID` + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```csharp +EnvironmentArchiveParams parameters = new() +{ + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW" +}; + +var betaEnvironment = await client.Beta.Environments.Archive(parameters); + +Console.WriteLine(betaEnvironment); +``` diff --git a/content/en/api/csharp/beta/environments/create.md b/content/en/api/csharp/beta/environments/create.md new file mode 100644 index 000000000..9e7943614 --- /dev/null +++ b/content/en/api/csharp/beta/environments/create.md @@ -0,0 +1,198 @@ +## Create + +`BetaEnvironment Beta.Environments.Create(EnvironmentCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `EnvironmentCreateParams parameters` + + - `required string name` + + Body param: Human-readable name for the environment + + - `BetaCloudConfigParams? config` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `string? description` + + Body param: Optional description of the environment + + - `IReadOnlyDictionary metadata` + + Body param: User-provided metadata key-value pairs + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```csharp +EnvironmentCreateParams parameters = new() { Name = "python-data-analysis" }; + +var betaEnvironment = await client.Beta.Environments.Create(parameters); + +Console.WriteLine(betaEnvironment); +``` diff --git a/content/en/api/csharp/beta/environments/delete.md b/content/en/api/csharp/beta/environments/delete.md new file mode 100644 index 000000000..2f23db698 --- /dev/null +++ b/content/en/api/csharp/beta/environments/delete.md @@ -0,0 +1,86 @@ +## Delete + +`BetaEnvironmentDeleteResponse Beta.Environments.Delete(EnvironmentDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `EnvironmentDeleteParams parameters` + + - `required string environmentID` + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironmentDeleteResponse:` + + Response after deleting an environment. + + - `required string ID` + + Environment identifier + + - `JsonElement Type "environment_deleted"constant` + + The type of response + +### Example + +```csharp +EnvironmentDeleteParams parameters = new() +{ + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW" +}; + +var betaEnvironmentDeleteResponse = await client.Beta.Environments.Delete(parameters); + +Console.WriteLine(betaEnvironmentDeleteResponse); +``` diff --git a/content/en/api/csharp/beta/environments/list.md b/content/en/api/csharp/beta/environments/list.md new file mode 100644 index 000000000..76e193cf0 --- /dev/null +++ b/content/en/api/csharp/beta/environments/list.md @@ -0,0 +1,204 @@ +## List + +`EnvironmentListPageResponse Beta.Environments.List(EnvironmentListParams?parameters, CancellationTokencancellationToken = default)` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `EnvironmentListParams parameters` + + - `Boolean includeArchived` + + Query param: Include archived environments in the response + + - `Long limit` + + Query param: Maximum number of environments to return + + - `string? page` + + Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class EnvironmentListPageResponse:` + + Response when listing environments. + + This response model uses opaque cursor-based pagination. Use the `page` + query parameter with the value from `next_page` to fetch the next page. + + - `required IReadOnlyList Data` + + List of environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + + - `required string? NextPage` + + Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request. + +### Example + +```csharp +EnvironmentListParams parameters = new(); + +var page = await client.Beta.Environments.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` diff --git a/content/en/api/csharp/beta/environments/retrieve.md b/content/en/api/csharp/beta/environments/retrieve.md new file mode 100644 index 000000000..2a5439941 --- /dev/null +++ b/content/en/api/csharp/beta/environments/retrieve.md @@ -0,0 +1,184 @@ +## Retrieve + +`BetaEnvironment Beta.Environments.Retrieve(EnvironmentRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `EnvironmentRetrieveParams parameters` + + - `required string environmentID` + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```csharp +EnvironmentRetrieveParams parameters = new() +{ + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW" +}; + +var betaEnvironment = await client.Beta.Environments.Retrieve(parameters); + +Console.WriteLine(betaEnvironment); +``` diff --git a/content/en/api/csharp/beta/environments/update.md b/content/en/api/csharp/beta/environments/update.md new file mode 100644 index 000000000..0caa1992f --- /dev/null +++ b/content/en/api/csharp/beta/environments/update.md @@ -0,0 +1,205 @@ +## Update + +`BetaEnvironment Beta.Environments.Update(EnvironmentUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `EnvironmentUpdateParams parameters` + + - `required string environmentID` + + Path param + + - `BetaCloudConfigParams? config` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `string? description` + + Body param: Updated description of the environment + + - `IReadOnlyDictionary metadata` + + Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + + - `string? name` + + Body param: Updated name for the environment + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `required string ID` + + Environment identifier (e.g., 'env_...') + + - `required string? ArchivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `required BetaCloudConfig Config` + + `cloud` environment configuration. + + - `required Networking Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonElement Type "unrestricted"constant` + + Network policy type + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `required Boolean AllowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `required Boolean AllowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `required IReadOnlyList AllowedHosts` + + Specifies domains the container can reach. + + - `JsonElement Type "limited"constant` + + Network policy type + + - `required BetaPackages Packages` + + Package manager configuration. + + - `required IReadOnlyList Apt` + + Ubuntu/Debian packages to install + + - `required IReadOnlyList Cargo` + + Rust packages to install + + - `required IReadOnlyList Gem` + + Ruby packages to install + + - `required IReadOnlyList Go` + + Go packages to install + + - `required IReadOnlyList Npm` + + Node.js packages to install + + - `required IReadOnlyList Pip` + + Python packages to install + + - `Type Type` + + Package configuration type + + - `"packages"Packages` + + - `JsonElement Type "cloud"constant` + + Environment type + + - `required string CreatedAt` + + RFC 3339 timestamp when environment was created + + - `required string Description` + + User-provided description for the environment + + - `required IReadOnlyDictionary Metadata` + + User-provided metadata key-value pairs + + - `required string Name` + + Human-readable name for the environment + + - `JsonElement Type "environment"constant` + + The type of object (always 'environment') + + - `required string UpdatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```csharp +EnvironmentUpdateParams parameters = new() +{ + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW" +}; + +var betaEnvironment = await client.Beta.Environments.Update(parameters); + +Console.WriteLine(betaEnvironment); +``` diff --git a/content/en/api/csharp/beta/files.md b/content/en/api/csharp/beta/files.md index 6d97185f1..bc3a1f0a6 100644 --- a/content/en/api/csharp/beta/files.md +++ b/content/en/api/csharp/beta/files.md @@ -62,8 +62,6 @@ Upload File - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class FileMetadata:` @@ -100,6 +98,18 @@ Upload File Whether the file can be downloaded. + - `BetaFileScope? Scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). + ### Example ```csharp @@ -139,6 +149,10 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. + - `string scopeID` + + Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `IReadOnlyList betas` Header param: Optional header to specify the beta version(s) you want to use. @@ -185,8 +199,6 @@ List Files - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class FileListPageResponse:` @@ -227,6 +239,18 @@ List Files Whether the file can be downloaded. + - `BetaFileScope? Scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). + - `string? FirstID` ID of the first file in this page of results. @@ -313,8 +337,6 @@ Download File - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Example ```csharp @@ -387,8 +409,6 @@ Get File Metadata - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class FileMetadata:` @@ -425,6 +445,18 @@ Get File Metadata Whether the file can be downloaded. + - `BetaFileScope? Scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). + ### Example ```csharp @@ -497,8 +529,6 @@ Delete File - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class DeletedFile:` @@ -527,6 +557,18 @@ Console.WriteLine(deletedFile); ## Domain Types +### Beta File Scope + +- `class BetaFileScope:` + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). + ### Deleted File - `class DeletedFile:` @@ -578,3 +620,15 @@ Console.WriteLine(deletedFile); - `Boolean Downloadable` Whether the file can be downloaded. + + - `BetaFileScope? Scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). diff --git a/content/en/api/csharp/beta/files/delete.md b/content/en/api/csharp/beta/files/delete.md index de5acdea8..a17f02dc4 100644 --- a/content/en/api/csharp/beta/files/delete.md +++ b/content/en/api/csharp/beta/files/delete.md @@ -60,8 +60,6 @@ Delete File - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class DeletedFile:` diff --git a/content/en/api/csharp/beta/files/download.md b/content/en/api/csharp/beta/files/download.md index 756aa1cc5..3002bb749 100644 --- a/content/en/api/csharp/beta/files/download.md +++ b/content/en/api/csharp/beta/files/download.md @@ -60,8 +60,6 @@ Download File - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Example ```csharp diff --git a/content/en/api/csharp/beta/files/list.md b/content/en/api/csharp/beta/files/list.md index 81859978f..fb48b1b4d 100644 --- a/content/en/api/csharp/beta/files/list.md +++ b/content/en/api/csharp/beta/files/list.md @@ -24,6 +24,10 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. + - `string scopeID` + + Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `IReadOnlyList betas` Header param: Optional header to specify the beta version(s) you want to use. @@ -70,8 +74,6 @@ List Files - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class FileListPageResponse:` @@ -112,6 +114,18 @@ List Files Whether the file can be downloaded. + - `BetaFileScope? Scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). + - `string? FirstID` ID of the first file in this page of results. diff --git a/content/en/api/csharp/beta/files/retrieve_metadata.md b/content/en/api/csharp/beta/files/retrieve_metadata.md index 8f47c3f16..8b3539326 100644 --- a/content/en/api/csharp/beta/files/retrieve_metadata.md +++ b/content/en/api/csharp/beta/files/retrieve_metadata.md @@ -60,8 +60,6 @@ Get File Metadata - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class FileMetadata:` @@ -98,6 +96,18 @@ Get File Metadata Whether the file can be downloaded. + - `BetaFileScope? Scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). + ### Example ```csharp diff --git a/content/en/api/csharp/beta/files/upload.md b/content/en/api/csharp/beta/files/upload.md index 55c9c5f04..39f8358e8 100644 --- a/content/en/api/csharp/beta/files/upload.md +++ b/content/en/api/csharp/beta/files/upload.md @@ -60,8 +60,6 @@ Upload File - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class FileMetadata:` @@ -98,6 +96,18 @@ Upload File Whether the file can be downloaded. + - `BetaFileScope? Scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `required string ID` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonElement Type "session"constant` + + The type of scope (e.g., `"session"`). + ### Example ```csharp diff --git a/content/en/api/csharp/beta/messages.md b/content/en/api/csharp/beta/messages.md index e942144ca..5200e7641 100644 --- a/content/en/api/csharp/beta/messages.md +++ b/content/en/api/csharp/beta/messages.md @@ -3843,10 +3843,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. - - `string? userProfileID` - - Body param: The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `IReadOnlyList betas` Header param: Optional header to specify the beta version(s) you want to use. @@ -3893,8 +3889,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessage:` @@ -4690,9 +4684,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -8796,8 +8794,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageTokensCount:` @@ -8827,7 +8823,7 @@ MessageCountTokensParams parameters = new() Role = Role.User, }, ], - Model = Model.ClaudeOpus4_6, + Model = Model.ClaudeMythosPreview, }; var betaMessageTokensCount = await client.Beta.Messages.CountTokens(parameters); @@ -14962,9 +14958,13 @@ Console.WriteLine(betaMessageTokensCount); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -19614,9 +19614,13 @@ Console.WriteLine(betaMessageTokensCount); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -20708,9 +20712,13 @@ Console.WriteLine(betaMessageTokensCount); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -30512,9 +30520,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -32395,10 +32407,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `string? UserProfileID` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `IReadOnlyList betas` Header param: Optional header to specify the beta version(s) you want to use. @@ -32445,8 +32453,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatch:` @@ -32703,7 +32709,6 @@ BatchCreateParams parameters = new() ], TopK = 5, TopP = 0.7, - UserProfileID = "user_profile_id", }, }, ], @@ -32778,8 +32783,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatch:` @@ -32952,8 +32955,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BatchListPageResponse:` @@ -33134,8 +33135,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatch:` @@ -33300,8 +33299,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaDeletedMessageBatch:` @@ -33392,8 +33389,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatchIndividualResponse:` @@ -34207,9 +34202,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -35578,9 +35577,13 @@ await foreach (var betaMessageBatchIndividualResponse in client.Beta.Messages.Ba See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -36776,9 +36779,13 @@ await foreach (var betaMessageBatchIndividualResponse in client.Beta.Messages.Ba See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -37936,9 +37943,13 @@ await foreach (var betaMessageBatchIndividualResponse in client.Beta.Messages.Ba See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` diff --git a/content/en/api/csharp/beta/messages/batches.md b/content/en/api/csharp/beta/messages/batches.md index 335f474d9..3d9236a08 100644 --- a/content/en/api/csharp/beta/messages/batches.md +++ b/content/en/api/csharp/beta/messages/batches.md @@ -2269,9 +2269,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -4152,10 +4156,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `string? UserProfileID` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `IReadOnlyList betas` Header param: Optional header to specify the beta version(s) you want to use. @@ -4202,8 +4202,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatch:` @@ -4460,7 +4458,6 @@ BatchCreateParams parameters = new() ], TopK = 5, TopP = 0.7, - UserProfileID = "user_profile_id", }, }, ], @@ -4535,8 +4532,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatch:` @@ -4709,8 +4704,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BatchListPageResponse:` @@ -4891,8 +4884,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatch:` @@ -5057,8 +5048,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaDeletedMessageBatch:` @@ -5149,8 +5138,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatchIndividualResponse:` @@ -5964,9 +5951,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -7335,9 +7326,13 @@ await foreach (var betaMessageBatchIndividualResponse in client.Beta.Messages.Ba See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -8533,9 +8528,13 @@ await foreach (var betaMessageBatchIndividualResponse in client.Beta.Messages.Ba See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -9693,9 +9692,13 @@ await foreach (var betaMessageBatchIndividualResponse in client.Beta.Messages.Ba See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` diff --git a/content/en/api/csharp/beta/messages/batches/cancel.md b/content/en/api/csharp/beta/messages/batches/cancel.md index 940e86fbe..d8f4e09ac 100644 --- a/content/en/api/csharp/beta/messages/batches/cancel.md +++ b/content/en/api/csharp/beta/messages/batches/cancel.md @@ -64,8 +64,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatch:` diff --git a/content/en/api/csharp/beta/messages/batches/create.md b/content/en/api/csharp/beta/messages/batches/create.md index e166c4080..456158959 100644 --- a/content/en/api/csharp/beta/messages/batches/create.md +++ b/content/en/api/csharp/beta/messages/batches/create.md @@ -2267,9 +2267,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -4150,10 +4154,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `string? UserProfileID` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `IReadOnlyList betas` Header param: Optional header to specify the beta version(s) you want to use. @@ -4200,8 +4200,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatch:` @@ -4458,7 +4456,6 @@ BatchCreateParams parameters = new() ], TopK = 5, TopP = 0.7, - UserProfileID = "user_profile_id", }, }, ], diff --git a/content/en/api/csharp/beta/messages/batches/delete.md b/content/en/api/csharp/beta/messages/batches/delete.md index 2bbfc8e71..de0cec201 100644 --- a/content/en/api/csharp/beta/messages/batches/delete.md +++ b/content/en/api/csharp/beta/messages/batches/delete.md @@ -64,8 +64,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaDeletedMessageBatch:` diff --git a/content/en/api/csharp/beta/messages/batches/list.md b/content/en/api/csharp/beta/messages/batches/list.md index 40b45ba44..af714accc 100644 --- a/content/en/api/csharp/beta/messages/batches/list.md +++ b/content/en/api/csharp/beta/messages/batches/list.md @@ -72,8 +72,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BatchListPageResponse:` diff --git a/content/en/api/csharp/beta/messages/batches/results.md b/content/en/api/csharp/beta/messages/batches/results.md index 075bbbba3..c9b05a0e3 100644 --- a/content/en/api/csharp/beta/messages/batches/results.md +++ b/content/en/api/csharp/beta/messages/batches/results.md @@ -64,8 +64,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatchIndividualResponse:` @@ -879,9 +877,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` diff --git a/content/en/api/csharp/beta/messages/batches/retrieve.md b/content/en/api/csharp/beta/messages/batches/retrieve.md index 120cd39b4..759e7229d 100644 --- a/content/en/api/csharp/beta/messages/batches/retrieve.md +++ b/content/en/api/csharp/beta/messages/batches/retrieve.md @@ -62,8 +62,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageBatch:` diff --git a/content/en/api/csharp/beta/messages/count_tokens.md b/content/en/api/csharp/beta/messages/count_tokens.md index 7da0539c7..87f80a717 100644 --- a/content/en/api/csharp/beta/messages/count_tokens.md +++ b/content/en/api/csharp/beta/messages/count_tokens.md @@ -3795,8 +3795,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessageTokensCount:` @@ -3826,7 +3824,7 @@ MessageCountTokensParams parameters = new() Role = Role.User, }, ], - Model = Model.ClaudeOpus4_6, + Model = Model.ClaudeMythosPreview, }; var betaMessageTokensCount = await client.Beta.Messages.CountTokens(parameters); diff --git a/content/en/api/csharp/beta/messages/create.md b/content/en/api/csharp/beta/messages/create.md index 12ed43cbc..a1ce597e6 100644 --- a/content/en/api/csharp/beta/messages/create.md +++ b/content/en/api/csharp/beta/messages/create.md @@ -3841,10 +3841,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. - - `string? userProfileID` - - Body param: The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `IReadOnlyList betas` Header param: Optional header to specify the beta version(s) you want to use. @@ -3891,8 +3887,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaMessage:` @@ -4688,9 +4682,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` diff --git a/content/en/api/csharp/beta/models.md b/content/en/api/csharp/beta/models.md index f900cde32..fe0a0a7b3 100644 --- a/content/en/api/csharp/beta/models.md +++ b/content/en/api/csharp/beta/models.md @@ -74,8 +74,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class ModelListPageResponse:` @@ -348,8 +346,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaModelInfo:` diff --git a/content/en/api/csharp/beta/models/list.md b/content/en/api/csharp/beta/models/list.md index 99701c992..aec631a6e 100644 --- a/content/en/api/csharp/beta/models/list.md +++ b/content/en/api/csharp/beta/models/list.md @@ -72,8 +72,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class ModelListPageResponse:` diff --git a/content/en/api/csharp/beta/models/retrieve.md b/content/en/api/csharp/beta/models/retrieve.md index 231d82a10..8a883df44 100644 --- a/content/en/api/csharp/beta/models/retrieve.md +++ b/content/en/api/csharp/beta/models/retrieve.md @@ -62,8 +62,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class BetaModelInfo:` diff --git a/content/en/api/csharp/beta/sessions.md b/content/en/api/csharp/beta/sessions.md new file mode 100644 index 000000000..633a1cb55 --- /dev/null +++ b/content/en/api/csharp/beta/sessions.md @@ -0,0 +1,14073 @@ +# Sessions + +## Create + +`BetaManagedAgentsSession Beta.Sessions.Create(SessionCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `SessionCreateParams parameters` + + - `required Agent agent` + + Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `string` + + - `class BetaManagedAgentsAgentParams:` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `required string ID` + + The `agent` ID. + + - `required Type Type` + + - `"agent"Agent` + + - `Int Version` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + + - `required string environmentID` + + Body param: ID of the `environment` defining the container configuration for this session. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata attached to the session. + + - `IReadOnlyList resources` + + Body param: Resources (e.g. repositories, files) to mount into the session's container. + + - `class BetaManagedAgentsGitHubRepositoryResourceParams:` + + Mount a GitHub repository into the session's container. + + - `required string AuthorizationToken` + + GitHub authorization token used to clone the repository. + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required string Url` + + Github URL of the repository + + - `Checkout? Checkout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `string? MountPath` + + Mount path in the container. Defaults to `/workspace/`. + + - `class BetaManagedAgentsFileResourceParams:` + + Mount a file uploaded via the Files API into the session. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `string? MountPath` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `string? title` + + Body param: Human-readable session title. + + - `IReadOnlyList vaultIds` + + Body param: Vault IDs for stored credentials the agent can use during the session. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```csharp +SessionCreateParams parameters = new() +{ + Agent = "agent_011CZkYpogX7uDKUyvBTophP", + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW", +}; + +var betaManagedAgentsSession = await client.Beta.Sessions.Create(parameters); + +Console.WriteLine(betaManagedAgentsSession); +``` + +## List + +`SessionListPageResponse Beta.Sessions.List(SessionListParams?parameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `SessionListParams parameters` + + - `string agentID` + + Query param: Filter sessions created with this agent ID. + + - `Int agentVersion` + + Query param: Filter by agent version. Only applies when agent_id is also set. + + - `DateTimeOffset createdAtGt` + + Query param: Return sessions created after this time (exclusive). + + - `DateTimeOffset createdAtGte` + + Query param: Return sessions created at or after this time (inclusive). + + - `DateTimeOffset createdAtLt` + + Query param: Return sessions created before this time (exclusive). + + - `DateTimeOffset createdAtLte` + + Query param: Return sessions created at or before this time (inclusive). + + - `Boolean includeArchived` + + Query param: When true, includes archived sessions. Default: false (exclude archived). + + - `Int limit` + + Query param: Maximum number of results to return. + + - `Order order` + + Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `"asc"Asc` + + - `"desc"Desc` + + - `string page` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class SessionListPageResponse:` + + Paginated list of sessions. + + - `IReadOnlyList Data` + + List of sessions. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +SessionListParams parameters = new(); + +var page = await client.Beta.Sessions.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`BetaManagedAgentsSession Beta.Sessions.Retrieve(SessionRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `SessionRetrieveParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```csharp +SessionRetrieveParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var betaManagedAgentsSession = await client.Beta.Sessions.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsSession); +``` + +## Update + +`BetaManagedAgentsSession Beta.Sessions.Update(SessionUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `SessionUpdateParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + + - `string? title` + + Body param: Human-readable session title. + + - `IReadOnlyList vaultIds` + + Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```csharp +SessionUpdateParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var betaManagedAgentsSession = await client.Beta.Sessions.Update(parameters); + +Console.WriteLine(betaManagedAgentsSession); +``` + +## Delete + +`BetaManagedAgentsDeletedSession Beta.Sessions.Delete(SessionDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `SessionDeleteParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeletedSession:` + + Confirmation that a `session` has been permanently deleted. + + - `required string ID` + + - `required Type Type` + + - `"session_deleted"SessionDeleted` + +### Example + +```csharp +SessionDeleteParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var betaManagedAgentsDeletedSession = await client.Beta.Sessions.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeletedSession); +``` + +## Archive + +`BetaManagedAgentsSession Beta.Sessions.Archive(SessionArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `SessionArchiveParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```csharp +SessionArchiveParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var betaManagedAgentsSession = await client.Beta.Sessions.Archive(parameters); + +Console.WriteLine(betaManagedAgentsSession); +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `class BetaManagedAgentsAgentParams:` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `required string ID` + + The `agent` ID. + + - `required Type Type` + + - `"agent"Agent` + + - `Int Version` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + +### Beta Managed Agents Cache Creation Usage + +- `class BetaManagedAgentsCacheCreationUsage:` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + +### Beta Managed Agents Deleted Session + +- `class BetaManagedAgentsDeletedSession:` + + Confirmation that a `session` has been permanently deleted. + + - `required string ID` + + - `required Type Type` + + - `"session_deleted"SessionDeleted` + +### Beta Managed Agents File Resource Params + +- `class BetaManagedAgentsFileResourceParams:` + + Mount a file uploaded via the Files API into the session. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `string? MountPath` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `class BetaManagedAgentsGitHubRepositoryResourceParams:` + + Mount a GitHub repository into the session's container. + + - `required string AuthorizationToken` + + GitHub authorization token used to clone the repository. + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required string Url` + + Github URL of the repository + + - `Checkout? Checkout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `string? MountPath` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `class BetaManagedAgentsSessionAgent:` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + +### Beta Managed Agents Session Stats + +- `class BetaManagedAgentsSessionStats:` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `class BetaManagedAgentsSessionUsage:` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + +# Events + +## List + +`EventListPageResponse Beta.Sessions.Events.List(EventListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `EventListParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `Int limit` + + Query param: Query parameter for limit + + - `Order order` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"Asc` + + - `"desc"Desc` + + - `string page` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class EventListPageResponse:` + + Paginated list of events for a `session`. + + - `IReadOnlyList Data` + + Events for the session, ordered by `created_at`. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +EventListParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var page = await client.Beta.Sessions.Events.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Send + +`BetaManagedAgentsSendSessionEvents Beta.Sessions.Events.Send(EventSendParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `EventSendParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required IReadOnlyList events` + + Body param: Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `required IReadOnlyList Content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSendSessionEvents:` + + Events that were successfully sent to the session. + + - `IReadOnlyList Data` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +EventSendParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + Events = + [ + new BetaManagedAgentsUserMessageEventParams() + { + Content = + [ + new BetaManagedAgentsTextBlock() + { + Text = "Where is my order #1234?", + Type = Type.Text, + }, + ], + Type = Type.UserMessage, + }, + ], +}; + +var betaManagedAgentsSendSessionEvents = await client.Beta.Sessions.Events.Send(parameters); + +Console.WriteLine(betaManagedAgentsSendSessionEvents); +``` + +## Stream + +`BetaManagedAgentsStreamSessionEvents Beta.Sessions.Events.StreamStreaming(EventStreamParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `EventStreamParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Example + +```csharp +EventStreamParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +await foreach (var betaManagedAgentsStreamSessionEvents in client.Beta.Sessions.Events.StreamStreaming(parameters)) +{ + Console.WriteLine(betaManagedAgentsStreamSessionEvents); +} +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + +### Beta Managed Agents Agent Message Event + +- `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + +### Beta Managed Agents Agent Thinking Event + +- `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + +### Beta Managed Agents Agent Tool Result Event + +- `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + +### Beta Managed Agents Base64 Document Source + +- `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + +### Beta Managed Agents Base64 Image Source + +- `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + +### Beta Managed Agents Billing Error + +- `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + +### Beta Managed Agents Document Block + +- `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + +### Beta Managed Agents Event Params + +- `class BetaManagedAgentsEventParams: A class that can be one of several variants.union` + + Union type for event parameters that can be sent to a session. + + - `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `required IReadOnlyList Content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + +### Beta Managed Agents File Image Source + +- `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + +### Beta Managed Agents Image Block + +- `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + +### Beta Managed Agents MCP Authentication Failed Error + +- `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + +### Beta Managed Agents MCP Connection Failed Error + +- `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + +### Beta Managed Agents Model Overloaded Error + +- `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + +### Beta Managed Agents Model Rate Limited Error + +- `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + +### Beta Managed Agents Model Request Failed Error + +- `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + +### Beta Managed Agents Plain Text Document Source + +- `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + +### Beta Managed Agents Retry Status Exhausted + +- `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + +### Beta Managed Agents Retry Status Retrying + +- `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + +### Beta Managed Agents Retry Status Terminal + +- `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + +### Beta Managed Agents Send Session Events + +- `class BetaManagedAgentsSendSessionEvents:` + + Events that were successfully sent to the session. + + - `IReadOnlyList Data` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Beta Managed Agents Session End Turn + +- `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + +### Beta Managed Agents Session Error Event + +- `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + +### Beta Managed Agents Session Event + +- `class BetaManagedAgentsSessionEvent: A class that can be one of several variants.union` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Beta Managed Agents Session Requires Action + +- `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + +### Beta Managed Agents Session Retries Exhausted + +- `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + +### Beta Managed Agents Session Status Idle Event + +- `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + +### Beta Managed Agents Session Status Rescheduled Event + +- `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + +### Beta Managed Agents Session Status Running Event + +- `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + +### Beta Managed Agents Session Status Terminated Event + +- `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + +### Beta Managed Agents Span Model Request End Event + +- `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + +### Beta Managed Agents Span Model Request Start Event + +- `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + +### Beta Managed Agents Span Model Usage + +- `class BetaManagedAgentsSpanModelUsage:` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + +### Beta Managed Agents Stream Session Events + +- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Beta Managed Agents Text Block + +- `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + +### Beta Managed Agents Unknown Error + +- `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + +### Beta Managed Agents URL Document Source + +- `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + +### Beta Managed Agents User Message Event + +- `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `required IReadOnlyList Content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + +### Beta Managed Agents User Tool Confirmation Event + +- `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`BetaManagedAgentsFileResource Beta.Sessions.Resources.Add(ResourceAddParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `ResourceAddParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string fileID` + + Body param: ID of a previously uploaded file. + + - `required Type type` + + Body param + + - `"file"File` + + - `string? mountPath` + + Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +ResourceAddParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + FileID = "file_011CNha8iCJcU1wXNR6q4V8w", + Type = Type.File, +}; + +var betaManagedAgentsFileResource = await client.Beta.Sessions.Resources.Add(parameters); + +Console.WriteLine(betaManagedAgentsFileResource); +``` + +## List + +`ResourceListPageResponse Beta.Sessions.Resources.List(ResourceListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `ResourceListParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `Int limit` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `string page` + + Query param: Opaque cursor from a previous response's next_page field. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class ResourceListPageResponse:` + + Paginated list of resources attached to a session. + + - `required IReadOnlyList Data` + + Resources for the session, ordered by `created_at`. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +ResourceListParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var page = await client.Beta.Sessions.Resources.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`ResourceRetrieveResponse Beta.Sessions.Resources.Retrieve(ResourceRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `ResourceRetrieveParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string resourceID` + + Path param: Path parameter resource_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class ResourceRetrieveResponse: A class that can be one of several variants.union` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +ResourceRetrieveParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + ResourceID = "sesrsc_011CZkZBJq5dWxk9fVLNcPht", +}; + +var resource = await client.Beta.Sessions.Resources.Retrieve(parameters); + +Console.WriteLine(resource); +``` + +## Update + +`ResourceUpdateResponse Beta.Sessions.Resources.Update(ResourceUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `ResourceUpdateParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string resourceID` + + Path param: Path parameter resource_id + + - `required string authorizationToken` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class ResourceUpdateResponse: A class that can be one of several variants.union` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +ResourceUpdateParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + ResourceID = "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + AuthorizationToken = "ghp_exampletoken", +}; + +var resource = await client.Beta.Sessions.Resources.Update(parameters); + +Console.WriteLine(resource); +``` + +## Delete + +`BetaManagedAgentsDeleteSessionResource Beta.Sessions.Resources.Delete(ResourceDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `ResourceDeleteParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string resourceID` + + Path param: Path parameter resource_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource:` + + Confirmation of resource deletion. + + - `required string ID` + + - `required Type Type` + + - `"session_resource_deleted"SessionResourceDeleted` + +### Example + +```csharp +ResourceDeleteParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + ResourceID = "sesrsc_011CZkZBJq5dWxk9fVLNcPht", +}; + +var betaManagedAgentsDeleteSessionResource = await client.Beta.Sessions.Resources.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeleteSessionResource); +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `class BetaManagedAgentsDeleteSessionResource:` + + Confirmation of resource deletion. + + - `required string ID` + + - `required Type Type` + + - `"session_resource_deleted"SessionResourceDeleted` + +### Beta Managed Agents File Resource + +- `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + +### Beta Managed Agents Session Resource + +- `class BetaManagedAgentsSessionResource: A class that can be one of several variants.union` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format diff --git a/content/en/api/csharp/beta/sessions/archive.md b/content/en/api/csharp/beta/sessions/archive.md new file mode 100644 index 000000000..8d9aa8e12 --- /dev/null +++ b/content/en/api/csharp/beta/sessions/archive.md @@ -0,0 +1,496 @@ +## Archive + +`BetaManagedAgentsSession Beta.Sessions.Archive(SessionArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `SessionArchiveParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```csharp +SessionArchiveParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var betaManagedAgentsSession = await client.Beta.Sessions.Archive(parameters); + +Console.WriteLine(betaManagedAgentsSession); +``` diff --git a/content/en/api/csharp/beta/sessions/create.md b/content/en/api/csharp/beta/sessions/create.md new file mode 100644 index 000000000..95c5a34c4 --- /dev/null +++ b/content/en/api/csharp/beta/sessions/create.md @@ -0,0 +1,595 @@ +## Create + +`BetaManagedAgentsSession Beta.Sessions.Create(SessionCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `SessionCreateParams parameters` + + - `required Agent agent` + + Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `string` + + - `class BetaManagedAgentsAgentParams:` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `required string ID` + + The `agent` ID. + + - `required Type Type` + + - `"agent"Agent` + + - `Int Version` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + + - `required string environmentID` + + Body param: ID of the `environment` defining the container configuration for this session. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata attached to the session. + + - `IReadOnlyList resources` + + Body param: Resources (e.g. repositories, files) to mount into the session's container. + + - `class BetaManagedAgentsGitHubRepositoryResourceParams:` + + Mount a GitHub repository into the session's container. + + - `required string AuthorizationToken` + + GitHub authorization token used to clone the repository. + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required string Url` + + Github URL of the repository + + - `Checkout? Checkout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `string? MountPath` + + Mount path in the container. Defaults to `/workspace/`. + + - `class BetaManagedAgentsFileResourceParams:` + + Mount a file uploaded via the Files API into the session. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `string? MountPath` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `string? title` + + Body param: Human-readable session title. + + - `IReadOnlyList vaultIds` + + Body param: Vault IDs for stored credentials the agent can use during the session. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```csharp +SessionCreateParams parameters = new() +{ + Agent = "agent_011CZkYpogX7uDKUyvBTophP", + EnvironmentID = "env_011CZkZ9X2dpNyB7HsEFoRfW", +}; + +var betaManagedAgentsSession = await client.Beta.Sessions.Create(parameters); + +Console.WriteLine(betaManagedAgentsSession); +``` diff --git a/content/en/api/csharp/beta/sessions/delete.md b/content/en/api/csharp/beta/sessions/delete.md new file mode 100644 index 000000000..a788e23dc --- /dev/null +++ b/content/en/api/csharp/beta/sessions/delete.md @@ -0,0 +1,86 @@ +## Delete + +`BetaManagedAgentsDeletedSession Beta.Sessions.Delete(SessionDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `SessionDeleteParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeletedSession:` + + Confirmation that a `session` has been permanently deleted. + + - `required string ID` + + - `required Type Type` + + - `"session_deleted"SessionDeleted` + +### Example + +```csharp +SessionDeleteParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var betaManagedAgentsDeletedSession = await client.Beta.Sessions.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeletedSession); +``` diff --git a/content/en/api/csharp/beta/sessions/events.md b/content/en/api/csharp/beta/sessions/events.md new file mode 100644 index 000000000..d23c36a3c --- /dev/null +++ b/content/en/api/csharp/beta/sessions/events.md @@ -0,0 +1,9652 @@ +# Events + +## List + +`EventListPageResponse Beta.Sessions.Events.List(EventListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `EventListParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `Int limit` + + Query param: Query parameter for limit + + - `Order order` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"Asc` + + - `"desc"Desc` + + - `string page` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class EventListPageResponse:` + + Paginated list of events for a `session`. + + - `IReadOnlyList Data` + + Events for the session, ordered by `created_at`. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +EventListParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var page = await client.Beta.Sessions.Events.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Send + +`BetaManagedAgentsSendSessionEvents Beta.Sessions.Events.Send(EventSendParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `EventSendParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required IReadOnlyList events` + + Body param: Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `required IReadOnlyList Content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSendSessionEvents:` + + Events that were successfully sent to the session. + + - `IReadOnlyList Data` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +EventSendParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + Events = + [ + new BetaManagedAgentsUserMessageEventParams() + { + Content = + [ + new BetaManagedAgentsTextBlock() + { + Text = "Where is my order #1234?", + Type = Type.Text, + }, + ], + Type = Type.UserMessage, + }, + ], +}; + +var betaManagedAgentsSendSessionEvents = await client.Beta.Sessions.Events.Send(parameters); + +Console.WriteLine(betaManagedAgentsSendSessionEvents); +``` + +## Stream + +`BetaManagedAgentsStreamSessionEvents Beta.Sessions.Events.StreamStreaming(EventStreamParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `EventStreamParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Example + +```csharp +EventStreamParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +await foreach (var betaManagedAgentsStreamSessionEvents in client.Beta.Sessions.Events.StreamStreaming(parameters)) +{ + Console.WriteLine(betaManagedAgentsStreamSessionEvents); +} +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + +### Beta Managed Agents Agent Message Event + +- `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + +### Beta Managed Agents Agent Thinking Event + +- `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + +### Beta Managed Agents Agent Tool Result Event + +- `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + +### Beta Managed Agents Base64 Document Source + +- `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + +### Beta Managed Agents Base64 Image Source + +- `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + +### Beta Managed Agents Billing Error + +- `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + +### Beta Managed Agents Document Block + +- `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + +### Beta Managed Agents Event Params + +- `class BetaManagedAgentsEventParams: A class that can be one of several variants.union` + + Union type for event parameters that can be sent to a session. + + - `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `required IReadOnlyList Content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + +### Beta Managed Agents File Image Source + +- `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + +### Beta Managed Agents Image Block + +- `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + +### Beta Managed Agents MCP Authentication Failed Error + +- `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + +### Beta Managed Agents MCP Connection Failed Error + +- `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + +### Beta Managed Agents Model Overloaded Error + +- `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + +### Beta Managed Agents Model Rate Limited Error + +- `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + +### Beta Managed Agents Model Request Failed Error + +- `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + +### Beta Managed Agents Plain Text Document Source + +- `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + +### Beta Managed Agents Retry Status Exhausted + +- `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + +### Beta Managed Agents Retry Status Retrying + +- `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + +### Beta Managed Agents Retry Status Terminal + +- `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + +### Beta Managed Agents Send Session Events + +- `class BetaManagedAgentsSendSessionEvents:` + + Events that were successfully sent to the session. + + - `IReadOnlyList Data` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Beta Managed Agents Session End Turn + +- `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + +### Beta Managed Agents Session Error Event + +- `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + +### Beta Managed Agents Session Event + +- `class BetaManagedAgentsSessionEvent: A class that can be one of several variants.union` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Beta Managed Agents Session Requires Action + +- `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + +### Beta Managed Agents Session Retries Exhausted + +- `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + +### Beta Managed Agents Session Status Idle Event + +- `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + +### Beta Managed Agents Session Status Rescheduled Event + +- `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + +### Beta Managed Agents Session Status Running Event + +- `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + +### Beta Managed Agents Session Status Terminated Event + +- `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + +### Beta Managed Agents Span Model Request End Event + +- `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + +### Beta Managed Agents Span Model Request Start Event + +- `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + +### Beta Managed Agents Span Model Usage + +- `class BetaManagedAgentsSpanModelUsage:` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + +### Beta Managed Agents Stream Session Events + +- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Beta Managed Agents Text Block + +- `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + +### Beta Managed Agents Unknown Error + +- `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + +### Beta Managed Agents URL Document Source + +- `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + +### Beta Managed Agents User Message Event + +- `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `required IReadOnlyList Content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + +### Beta Managed Agents User Tool Confirmation Event + +- `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. diff --git a/content/en/api/csharp/beta/sessions/events/list.md b/content/en/api/csharp/beta/sessions/events/list.md new file mode 100644 index 000000000..21236a8b0 --- /dev/null +++ b/content/en/api/csharp/beta/sessions/events/list.md @@ -0,0 +1,1470 @@ +## List + +`EventListPageResponse Beta.Sessions.Events.List(EventListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `EventListParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `Int limit` + + Query param: Query parameter for limit + + - `Order order` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"Asc` + + - `"desc"Desc` + + - `string page` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class EventListPageResponse:` + + Paginated list of events for a `session`. + + - `IReadOnlyList Data` + + Events for the session, ordered by `created_at`. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +EventListParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var page = await client.Beta.Sessions.Events.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` diff --git a/content/en/api/csharp/beta/sessions/events/send.md b/content/en/api/csharp/beta/sessions/events/send.md new file mode 100644 index 000000000..10c5eabd5 --- /dev/null +++ b/content/en/api/csharp/beta/sessions/events/send.md @@ -0,0 +1,831 @@ +## Send + +`BetaManagedAgentsSendSessionEvents Beta.Sessions.Events.Send(EventSendParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `EventSendParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required IReadOnlyList events` + + Body param: Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `required IReadOnlyList Content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSendSessionEvents:` + + Events that were successfully sent to the session. + + - `IReadOnlyList Data` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +EventSendParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + Events = + [ + new BetaManagedAgentsUserMessageEventParams() + { + Content = + [ + new BetaManagedAgentsTextBlock() + { + Text = "Where is my order #1234?", + Type = Type.Text, + }, + ], + Type = Type.UserMessage, + }, + ], +}; + +var betaManagedAgentsSendSessionEvents = await client.Beta.Sessions.Events.Send(parameters); + +Console.WriteLine(betaManagedAgentsSendSessionEvents); +``` diff --git a/content/en/api/csharp/beta/sessions/events/stream.md b/content/en/api/csharp/beta/sessions/events/stream.md new file mode 100644 index 000000000..c0742c024 --- /dev/null +++ b/content/en/api/csharp/beta/sessions/events/stream.md @@ -0,0 +1,1445 @@ +## Stream + +`BetaManagedAgentsStreamSessionEvents Beta.Sessions.Events.StreamStreaming(EventStreamParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `EventStreamParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `required Type Type` + + - `"user.message"UserMessage` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `required string ID` + + Unique identifier for this event. + + - `required Type Type` + + - `"user.interrupt"UserInterrupt` + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Result Result` + + UserToolConfirmationResult enum + + - `"allow"Allow` + + - `"deny"Deny` + + - `required string ToolUseID` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.tool_confirmation"UserToolConfirmation` + + - `string? DenyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string CustomToolUseID` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `required Type Type` + + - `"user.custom_tool_result"UserCustomToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `DateTimeOffset? ProcessedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the custom tool being called. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.custom_tool_use"AgentCustomToolUse` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyList Content` + + Array of text blocks comprising the agent response. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.message"AgentMessage` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thinking"AgentThinking` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string McpServerName` + + Name of the MCP server providing the tool. + + - `required string Name` + + Name of the MCP tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_use"AgentMcpToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required string McpToolUseID` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.mcp_tool_result"AgentMcpToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `required string ID` + + Unique identifier for this event. + + - `required IReadOnlyDictionary Input` + + Input parameters for the tool call. + + - `required string Name` + + Name of the agent tool being used. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.tool_use"AgentToolUse` + + - `EvaluatedPermission EvaluatedPermission` + + AgentEvaluatedPermission enum + + - `"allow"Allow` + + - `"ask"Ask` + + - `"deny"Deny` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required string ToolUseID` + + The id of the `agent.tool_use` event this result corresponds to. + + - `required Type Type` + + - `"agent.tool_result"AgentToolResult` + + - `IReadOnlyList Content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `required string Text` + + The text content. + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `required Source Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `required string Data` + + Base64-encoded image data. + + - `required string MediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"image"Image` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `required Source Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `required string Data` + + Base64-encoded document data. + + - `required string MediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `required Type Type` + + - `"base64"Base64` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `required string Data` + + The plain text content. + + - `required MediaType MediaType` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"TextPlain` + + - `required Type Type` + + - `"text"Text` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `required string FileID` + + ID of a previously uploaded file. + + - `required Type Type` + + - `"file"File` + + - `required Type Type` + + - `"document"Document` + + - `string? Context` + + Additional context about the document for the model. + + - `string? Title` + + The title of the document. + + - `Boolean? IsError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"agent.thread_context_compacted"AgentThreadContextCompacted` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `required string ID` + + Unique identifier for this event. + + - `required Error Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"unknown_error"UnknownError` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_overloaded_error"ModelOverloadedError` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_rate_limited_error"ModelRateLimitedError` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"model_request_failed_error"ModelRequestFailedError` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `required string McpServerName` + + Name of the MCP server that failed to connect. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_connection_failed_error"McpConnectionFailedError` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `required string McpServerName` + + Name of the MCP server that failed authentication. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"mcp_authentication_failed_error"McpAuthenticationFailedError` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `required string Message` + + Human-readable error description. + + - `required RetryStatus RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `required Type Type` + + - `"retrying"Retrying` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `required Type Type` + + - `"exhausted"Exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `required Type Type` + + - `"terminal"Terminal` + + - `required Type Type` + + - `"billing_error"BillingError` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.error"SessionError` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_rescheduled"SessionStatusRescheduled` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_running"SessionStatusRunning` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required StopReason StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `required Type Type` + + - `"end_turn"EndTurn` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `required IReadOnlyList EventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `required Type Type` + + - `"requires_action"RequiresAction` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `required Type Type` + + - `"retries_exhausted"RetriesExhausted` + + - `required Type Type` + + - `"session.status_idle"SessionStatusIdle` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.status_terminated"SessionStatusTerminated` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_start"SpanModelRequestStart` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `required string ID` + + Unique identifier for this event. + + - `required Boolean? IsError` + + Whether the model request resulted in an error. + + - `required string ModelRequestStartID` + + The id of the corresponding `span.model_request_start` event. + + - `required BetaManagedAgentsSpanModelUsage ModelUsage` + + Token usage for a single model request. + + - `required Int CacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `required Int CacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `required Int InputTokens` + + Input tokens consumed by this request. + + - `required Int OutputTokens` + + Output tokens generated by this request. + + - `Speed? Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"span.model_request_end"SpanModelRequestEnd` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `required string ID` + + Unique identifier for this event. + + - `required DateTimeOffset ProcessedAt` + + A timestamp in RFC 3339 format + + - `required Type Type` + + - `"session.deleted"SessionDeleted` + +### Example + +```csharp +EventStreamParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +await foreach (var betaManagedAgentsStreamSessionEvents in client.Beta.Sessions.Events.StreamStreaming(parameters)) +{ + Console.WriteLine(betaManagedAgentsStreamSessionEvents); +} +``` diff --git a/content/en/api/csharp/beta/sessions/list.md b/content/en/api/csharp/beta/sessions/list.md new file mode 100644 index 000000000..5e5c58123 --- /dev/null +++ b/content/en/api/csharp/beta/sessions/list.md @@ -0,0 +1,543 @@ +## List + +`SessionListPageResponse Beta.Sessions.List(SessionListParams?parameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `SessionListParams parameters` + + - `string agentID` + + Query param: Filter sessions created with this agent ID. + + - `Int agentVersion` + + Query param: Filter by agent version. Only applies when agent_id is also set. + + - `DateTimeOffset createdAtGt` + + Query param: Return sessions created after this time (exclusive). + + - `DateTimeOffset createdAtGte` + + Query param: Return sessions created at or after this time (inclusive). + + - `DateTimeOffset createdAtLt` + + Query param: Return sessions created before this time (exclusive). + + - `DateTimeOffset createdAtLte` + + Query param: Return sessions created at or before this time (inclusive). + + - `Boolean includeArchived` + + Query param: When true, includes archived sessions. Default: false (exclude archived). + + - `Int limit` + + Query param: Maximum number of results to return. + + - `Order order` + + Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `"asc"Asc` + + - `"desc"Desc` + + - `string page` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class SessionListPageResponse:` + + Paginated list of sessions. + + - `IReadOnlyList Data` + + List of sessions. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +SessionListParams parameters = new(); + +var page = await client.Beta.Sessions.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` diff --git a/content/en/api/csharp/beta/sessions/resources.md b/content/en/api/csharp/beta/sessions/resources.md new file mode 100644 index 000000000..80f328857 --- /dev/null +++ b/content/en/api/csharp/beta/sessions/resources.md @@ -0,0 +1,814 @@ +# Resources + +## Add + +`BetaManagedAgentsFileResource Beta.Sessions.Resources.Add(ResourceAddParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `ResourceAddParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string fileID` + + Body param: ID of a previously uploaded file. + + - `required Type type` + + Body param + + - `"file"File` + + - `string? mountPath` + + Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +ResourceAddParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + FileID = "file_011CNha8iCJcU1wXNR6q4V8w", + Type = Type.File, +}; + +var betaManagedAgentsFileResource = await client.Beta.Sessions.Resources.Add(parameters); + +Console.WriteLine(betaManagedAgentsFileResource); +``` + +## List + +`ResourceListPageResponse Beta.Sessions.Resources.List(ResourceListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `ResourceListParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `Int limit` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `string page` + + Query param: Opaque cursor from a previous response's next_page field. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class ResourceListPageResponse:` + + Paginated list of resources attached to a session. + + - `required IReadOnlyList Data` + + Resources for the session, ordered by `created_at`. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +ResourceListParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var page = await client.Beta.Sessions.Resources.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`ResourceRetrieveResponse Beta.Sessions.Resources.Retrieve(ResourceRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `ResourceRetrieveParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string resourceID` + + Path param: Path parameter resource_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class ResourceRetrieveResponse: A class that can be one of several variants.union` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +ResourceRetrieveParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + ResourceID = "sesrsc_011CZkZBJq5dWxk9fVLNcPht", +}; + +var resource = await client.Beta.Sessions.Resources.Retrieve(parameters); + +Console.WriteLine(resource); +``` + +## Update + +`ResourceUpdateResponse Beta.Sessions.Resources.Update(ResourceUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `ResourceUpdateParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string resourceID` + + Path param: Path parameter resource_id + + - `required string authorizationToken` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class ResourceUpdateResponse: A class that can be one of several variants.union` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +ResourceUpdateParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + ResourceID = "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + AuthorizationToken = "ghp_exampletoken", +}; + +var resource = await client.Beta.Sessions.Resources.Update(parameters); + +Console.WriteLine(resource); +``` + +## Delete + +`BetaManagedAgentsDeleteSessionResource Beta.Sessions.Resources.Delete(ResourceDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `ResourceDeleteParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string resourceID` + + Path param: Path parameter resource_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource:` + + Confirmation of resource deletion. + + - `required string ID` + + - `required Type Type` + + - `"session_resource_deleted"SessionResourceDeleted` + +### Example + +```csharp +ResourceDeleteParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + ResourceID = "sesrsc_011CZkZBJq5dWxk9fVLNcPht", +}; + +var betaManagedAgentsDeleteSessionResource = await client.Beta.Sessions.Resources.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeleteSessionResource); +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `class BetaManagedAgentsDeleteSessionResource:` + + Confirmation of resource deletion. + + - `required string ID` + + - `required Type Type` + + - `"session_resource_deleted"SessionResourceDeleted` + +### Beta Managed Agents File Resource + +- `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + +### Beta Managed Agents Session Resource + +- `class BetaManagedAgentsSessionResource: A class that can be one of several variants.union` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format diff --git a/content/en/api/csharp/beta/sessions/resources/add.md b/content/en/api/csharp/beta/sessions/resources/add.md new file mode 100644 index 000000000..bf445b11a --- /dev/null +++ b/content/en/api/csharp/beta/sessions/resources/add.md @@ -0,0 +1,112 @@ +## Add + +`BetaManagedAgentsFileResource Beta.Sessions.Resources.Add(ResourceAddParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `ResourceAddParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string fileID` + + Body param: ID of a previously uploaded file. + + - `required Type type` + + Body param + + - `"file"File` + + - `string? mountPath` + + Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +ResourceAddParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + FileID = "file_011CNha8iCJcU1wXNR6q4V8w", + Type = Type.File, +}; + +var betaManagedAgentsFileResource = await client.Beta.Sessions.Resources.Add(parameters); + +Console.WriteLine(betaManagedAgentsFileResource); +``` diff --git a/content/en/api/csharp/beta/sessions/resources/delete.md b/content/en/api/csharp/beta/sessions/resources/delete.md new file mode 100644 index 000000000..f99c7cc96 --- /dev/null +++ b/content/en/api/csharp/beta/sessions/resources/delete.md @@ -0,0 +1,91 @@ +## Delete + +`BetaManagedAgentsDeleteSessionResource Beta.Sessions.Resources.Delete(ResourceDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `ResourceDeleteParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string resourceID` + + Path param: Path parameter resource_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource:` + + Confirmation of resource deletion. + + - `required string ID` + + - `required Type Type` + + - `"session_resource_deleted"SessionResourceDeleted` + +### Example + +```csharp +ResourceDeleteParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + ResourceID = "sesrsc_011CZkZBJq5dWxk9fVLNcPht", +}; + +var betaManagedAgentsDeleteSessionResource = await client.Beta.Sessions.Resources.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeleteSessionResource); +``` diff --git a/content/en/api/csharp/beta/sessions/resources/list.md b/content/en/api/csharp/beta/sessions/resources/list.md new file mode 100644 index 000000000..c44abc391 --- /dev/null +++ b/content/en/api/csharp/beta/sessions/resources/list.md @@ -0,0 +1,160 @@ +## List + +`ResourceListPageResponse Beta.Sessions.Resources.List(ResourceListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `ResourceListParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `Int limit` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `string page` + + Query param: Opaque cursor from a previous response's next_page field. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class ResourceListPageResponse:` + + Paginated list of resources attached to a session. + + - `required IReadOnlyList Data` + + Resources for the session, ordered by `created_at`. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `string? NextPage` + + Opaque cursor for the next page. Null when no more results. + +### Example + +```csharp +ResourceListParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var page = await client.Beta.Sessions.Resources.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` diff --git a/content/en/api/csharp/beta/sessions/resources/retrieve.md b/content/en/api/csharp/beta/sessions/resources/retrieve.md new file mode 100644 index 000000000..c8b53f564 --- /dev/null +++ b/content/en/api/csharp/beta/sessions/resources/retrieve.md @@ -0,0 +1,147 @@ +## Retrieve + +`ResourceRetrieveResponse Beta.Sessions.Resources.Retrieve(ResourceRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `ResourceRetrieveParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string resourceID` + + Path param: Path parameter resource_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class ResourceRetrieveResponse: A class that can be one of several variants.union` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +ResourceRetrieveParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + ResourceID = "sesrsc_011CZkZBJq5dWxk9fVLNcPht", +}; + +var resource = await client.Beta.Sessions.Resources.Retrieve(parameters); + +Console.WriteLine(resource); +``` diff --git a/content/en/api/csharp/beta/sessions/resources/update.md b/content/en/api/csharp/beta/sessions/resources/update.md new file mode 100644 index 000000000..0dee54aca --- /dev/null +++ b/content/en/api/csharp/beta/sessions/resources/update.md @@ -0,0 +1,152 @@ +## Update + +`ResourceUpdateResponse Beta.Sessions.Resources.Update(ResourceUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `ResourceUpdateParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `required string resourceID` + + Path param: Path parameter resource_id + + - `required string authorizationToken` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class ResourceUpdateResponse: A class that can be one of several variants.union` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +ResourceUpdateParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7", + ResourceID = "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + AuthorizationToken = "ghp_exampletoken", +}; + +var resource = await client.Beta.Sessions.Resources.Update(parameters); + +Console.WriteLine(resource); +``` diff --git a/content/en/api/csharp/beta/sessions/retrieve.md b/content/en/api/csharp/beta/sessions/retrieve.md new file mode 100644 index 000000000..252a56cd1 --- /dev/null +++ b/content/en/api/csharp/beta/sessions/retrieve.md @@ -0,0 +1,496 @@ +## Retrieve + +`BetaManagedAgentsSession Beta.Sessions.Retrieve(SessionRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `SessionRetrieveParams parameters` + + - `required string sessionID` + + Path parameter session_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```csharp +SessionRetrieveParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var betaManagedAgentsSession = await client.Beta.Sessions.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsSession); +``` diff --git a/content/en/api/csharp/beta/sessions/update.md b/content/en/api/csharp/beta/sessions/update.md new file mode 100644 index 000000000..77ce195df --- /dev/null +++ b/content/en/api/csharp/beta/sessions/update.md @@ -0,0 +1,508 @@ +## Update + +`BetaManagedAgentsSession Beta.Sessions.Update(SessionUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `SessionUpdateParams parameters` + + - `required string sessionID` + + Path param: Path parameter session_id + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + + - `string? title` + + Body param: Human-readable session title. + + - `IReadOnlyList vaultIds` + + Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `required string ID` + + - `required BetaManagedAgentsSessionAgent Agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `required string ID` + + - `required string? Description` + + - `required IReadOnlyList McpServers` + + - `required string Name` + + - `required Type Type` + + - `"url"Url` + + - `required string Url` + + - `required BetaManagedAgentsModelConfig Model` + + Model identifier and configuration. + + - `required BetaManagedAgentsModel ID` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6"ClaudeOpus4_6` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"ClaudeSonnet4_6` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"ClaudeHaiku4_5` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"ClaudeHaiku4_5_20251001` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"ClaudeOpus4_5` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"ClaudeOpus4_5_20251101` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"ClaudeSonnet4_5` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"ClaudeSonnet4_5_20250929` + + High-performance model for agents and coding + + - `Speed Speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"Standard` + + - `"fast"Fast` + + - `required string Name` + + - `required IReadOnlyList Skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `required string SkillID` + + - `required Type Type` + + - `"anthropic"Anthropic` + + - `required string Version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `required string SkillID` + + - `required Type Type` + + - `"custom"Custom` + + - `required string Version` + + - `required string? System` + + - `required IReadOnlyList Tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required Name Name` + + Built-in agent tool identifier. + + - `"bash"Bash` + + - `"edit"Edit` + + - `"read"Read` + + - `"write"Write` + + - `"glob"Glob` + + - `"grep"Grep` + + - `"web_fetch"WebFetch` + + - `"web_search"WebSearch` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsAgentToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for agent tools. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required Type Type` + + - `"agent_toolset_20260401"AgentToolset20260401` + + - `class BetaManagedAgentsMcpToolset:` + + - `required IReadOnlyList Configs` + + - `required Boolean Enabled` + + - `required string Name` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required BetaManagedAgentsMcpToolsetDefaultConfig DefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `required Boolean Enabled` + + - `required PermissionPolicy PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `required Type Type` + + - `"always_allow"AlwaysAllow` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `required Type Type` + + - `"always_ask"AlwaysAsk` + + - `required string McpServerName` + + - `required Type Type` + + - `"mcp_toolset"McpToolset` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `required string Description` + + - `required BetaManagedAgentsCustomToolInputSchema InputSchema` + + JSON Schema for custom tool input parameters. + + - `IReadOnlyDictionary? Properties` + + JSON Schema properties defining the tool's input parameters. + + - `IReadOnlyList Required` + + List of required property names. + + - `Type Type` + + Must be 'object' for tool input schemas. + + - `"object"Object` + + - `required string Name` + + - `required Type Type` + + - `"custom"Custom` + + - `required Type Type` + + - `"agent"Agent` + + - `required Int Version` + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string EnvironmentID` + + - `required IReadOnlyDictionary Metadata` + + - `required IReadOnlyList Resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string MountPath` + + - `required Type Type` + + - `"github_repository"GitHubRepository` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string Url` + + - `Checkout? Checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `required string Name` + + Branch name to check out. + + - `required Type Type` + + - `"branch"Branch` + + - `class BetaManagedAgentsCommitCheckout:` + + - `required string Sha` + + Full commit SHA to check out. + + - `required Type Type` + + - `"commit"Commit` + + - `class BetaManagedAgentsFileResource:` + + - `required string ID` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string FileID` + + - `required string MountPath` + + - `required Type Type` + + - `"file"File` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionStats Stats` + + Timing statistics for a session. + + - `Double ActiveSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Double DurationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `required Status Status` + + SessionStatus enum + + - `"rescheduling"Rescheduling` + + - `"running"Running` + + - `"idle"Idle` + + - `"terminated"Terminated` + + - `required string? Title` + + - `required Type Type` + + - `"session"Session` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required BetaManagedAgentsSessionUsage Usage` + + Cumulative token usage for a session across all turns. + + - `BetaManagedAgentsCacheCreationUsage CacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Int Ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Int Ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Int CacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Int InputTokens` + + Total input tokens consumed across all turns. + + - `Int OutputTokens` + + Total output tokens generated across all turns. + + - `required IReadOnlyList VaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```csharp +SessionUpdateParams parameters = new() +{ + SessionID = "sesn_011CZkZAtmR3yMPDzynEDxu7" +}; + +var betaManagedAgentsSession = await client.Beta.Sessions.Update(parameters); + +Console.WriteLine(betaManagedAgentsSession); +``` diff --git a/content/en/api/csharp/beta/skills.md b/content/en/api/csharp/beta/skills.md index 9d7c4f9e9..41e488824 100644 --- a/content/en/api/csharp/beta/skills.md +++ b/content/en/api/csharp/beta/skills.md @@ -70,8 +70,6 @@ Create Skill - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class SkillCreateResponse:` @@ -206,8 +204,6 @@ List Skills - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class SkillListPageResponse:` @@ -345,8 +341,6 @@ Get Skill - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class SkillRetrieveResponse:` @@ -466,8 +460,6 @@ Delete Skill - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class SkillDeleteResponse:` @@ -566,8 +558,6 @@ Create Skill Version - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionCreateResponse:` @@ -700,8 +690,6 @@ List Skill Versions - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionListPageResponse:` @@ -844,8 +832,6 @@ Get Skill Version - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionRetrieveResponse:` @@ -978,8 +964,6 @@ Delete Skill Version - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionDeleteResponse:` diff --git a/content/en/api/csharp/beta/skills/create.md b/content/en/api/csharp/beta/skills/create.md index e0c3aa4b6..fa5e09c71 100644 --- a/content/en/api/csharp/beta/skills/create.md +++ b/content/en/api/csharp/beta/skills/create.md @@ -68,8 +68,6 @@ Create Skill - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class SkillCreateResponse:` diff --git a/content/en/api/csharp/beta/skills/delete.md b/content/en/api/csharp/beta/skills/delete.md index f8bae7df6..cf1347e49 100644 --- a/content/en/api/csharp/beta/skills/delete.md +++ b/content/en/api/csharp/beta/skills/delete.md @@ -62,8 +62,6 @@ Delete Skill - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class SkillDeleteResponse:` diff --git a/content/en/api/csharp/beta/skills/list.md b/content/en/api/csharp/beta/skills/list.md index 7d875f696..476890294 100644 --- a/content/en/api/csharp/beta/skills/list.md +++ b/content/en/api/csharp/beta/skills/list.md @@ -77,8 +77,6 @@ List Skills - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class SkillListPageResponse:` diff --git a/content/en/api/csharp/beta/skills/retrieve.md b/content/en/api/csharp/beta/skills/retrieve.md index d0f38b3da..94db22875 100644 --- a/content/en/api/csharp/beta/skills/retrieve.md +++ b/content/en/api/csharp/beta/skills/retrieve.md @@ -62,8 +62,6 @@ Get Skill - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class SkillRetrieveResponse:` diff --git a/content/en/api/csharp/beta/skills/versions.md b/content/en/api/csharp/beta/skills/versions.md index 7f21fa68e..c2bbc487f 100644 --- a/content/en/api/csharp/beta/skills/versions.md +++ b/content/en/api/csharp/beta/skills/versions.md @@ -70,8 +70,6 @@ Create Skill Version - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionCreateResponse:` @@ -204,8 +202,6 @@ List Skill Versions - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionListPageResponse:` @@ -348,8 +344,6 @@ Get Skill Version - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionRetrieveResponse:` @@ -482,8 +476,6 @@ Delete Skill Version - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionDeleteResponse:` diff --git a/content/en/api/csharp/beta/skills/versions/create.md b/content/en/api/csharp/beta/skills/versions/create.md index 5fcd14d30..d6e15e088 100644 --- a/content/en/api/csharp/beta/skills/versions/create.md +++ b/content/en/api/csharp/beta/skills/versions/create.md @@ -68,8 +68,6 @@ Create Skill Version - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionCreateResponse:` diff --git a/content/en/api/csharp/beta/skills/versions/delete.md b/content/en/api/csharp/beta/skills/versions/delete.md index cba2130f9..e6613e852 100644 --- a/content/en/api/csharp/beta/skills/versions/delete.md +++ b/content/en/api/csharp/beta/skills/versions/delete.md @@ -68,8 +68,6 @@ Delete Skill Version - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionDeleteResponse:` diff --git a/content/en/api/csharp/beta/skills/versions/list.md b/content/en/api/csharp/beta/skills/versions/list.md index 5d2f6ef1a..4a2a42e01 100644 --- a/content/en/api/csharp/beta/skills/versions/list.md +++ b/content/en/api/csharp/beta/skills/versions/list.md @@ -72,8 +72,6 @@ List Skill Versions - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionListPageResponse:` diff --git a/content/en/api/csharp/beta/skills/versions/retrieve.md b/content/en/api/csharp/beta/skills/versions/retrieve.md index 0609c6415..8447faf29 100644 --- a/content/en/api/csharp/beta/skills/versions/retrieve.md +++ b/content/en/api/csharp/beta/skills/versions/retrieve.md @@ -68,8 +68,6 @@ Get Skill Version - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class VersionRetrieveResponse:` diff --git a/content/en/api/csharp/beta/vaults.md b/content/en/api/csharp/beta/vaults.md new file mode 100644 index 000000000..baa806670 --- /dev/null +++ b/content/en/api/csharp/beta/vaults.md @@ -0,0 +1,2637 @@ +# Vaults + +## Create + +`BetaManagedAgentsVault Beta.Vaults.Create(VaultCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `VaultCreateParams parameters` + + - `required string displayName` + + Body param: Human-readable name for the vault. 1-255 characters. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata to attach to the vault. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +VaultCreateParams parameters = new() { DisplayName = "Example vault" }; + +var betaManagedAgentsVault = await client.Beta.Vaults.Create(parameters); + +Console.WriteLine(betaManagedAgentsVault); +``` + +## List + +`VaultListPageResponse Beta.Vaults.List(VaultListParams?parameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `VaultListParams parameters` + + - `Boolean includeArchived` + + Query param: Whether to include archived vaults in the results. + + - `Int limit` + + Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. + + - `string page` + + Query param: Opaque pagination token from a previous `list_vaults` response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class VaultListPageResponse:` + + Response containing a paginated list of vaults. + + - `IReadOnlyList Data` + + List of vaults. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `string? NextPage` + + Pagination token for the next page, or null if no more results. + +### Example + +```csharp +VaultListParams parameters = new(); + +var page = await client.Beta.Vaults.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`BetaManagedAgentsVault Beta.Vaults.Retrieve(VaultRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `VaultRetrieveParams parameters` + + - `required string vaultID` + + Path parameter vault_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +VaultRetrieveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var betaManagedAgentsVault = await client.Beta.Vaults.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsVault); +``` + +## Update + +`BetaManagedAgentsVault Beta.Vaults.Update(VaultUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `VaultUpdateParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `string? displayName` + + Body param: Updated human-readable name for the vault. 1-255 characters. + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +VaultUpdateParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var betaManagedAgentsVault = await client.Beta.Vaults.Update(parameters); + +Console.WriteLine(betaManagedAgentsVault); +``` + +## Delete + +`BetaManagedAgentsDeletedVault Beta.Vaults.Delete(VaultDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `VaultDeleteParams parameters` + + - `required string vaultID` + + Path parameter vault_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeletedVault:` + + Confirmation of a deleted vault. + + - `required string ID` + + Unique identifier of the deleted vault. + + - `required Type Type` + + - `"vault_deleted"VaultDeleted` + +### Example + +```csharp +VaultDeleteParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var betaManagedAgentsDeletedVault = await client.Beta.Vaults.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeletedVault); +``` + +## Archive + +`BetaManagedAgentsVault Beta.Vaults.Archive(VaultArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `VaultArchiveParams parameters` + + - `required string vaultID` + + Path parameter vault_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +VaultArchiveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var betaManagedAgentsVault = await client.Beta.Vaults.Archive(parameters); + +Console.WriteLine(betaManagedAgentsVault); +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `class BetaManagedAgentsDeletedVault:` + + Confirmation of a deleted vault. + + - `required string ID` + + Unique identifier of the deleted vault. + + - `required Type Type` + + - `"vault_deleted"VaultDeleted` + +### Beta Managed Agents Vault + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Create(CredentialCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `CredentialCreateParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required Auth auth` + + Body param: Authentication details for creating a credential. + + - `class BetaManagedAgentsMcpOAuthCreateParams:` + + Parameters for creating an MCP OAuth credential. + + - `required string AccessToken` + + OAuth access token. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshParams? Refresh` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `required string ClientID` + + OAuth client ID. + + - `required string RefreshToken` + + OAuth refresh token. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams:` + + Parameters for creating a static bearer token credential. + + - `required string Token` + + Static bearer token value. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `string? displayName` + + Body param: Human-readable name for the credential. Up to 255 characters. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata to attach to the credential. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialCreateParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + Auth = new BetaManagedAgentsStaticBearerCreateParams() + { + Token = "bearer_exampletoken", + McpServerUrl = "https://example-server.modelcontextprotocol.io/sse", + Type = Type.StaticBearer, + }, +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Create(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` + +## List + +`CredentialListPageResponse Beta.Vaults.Credentials.List(CredentialListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `CredentialListParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `Boolean includeArchived` + + Query param: Whether to include archived credentials in the results. + + - `Int limit` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `string page` + + Query param: Opaque pagination token from a previous `list_credentials` response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class CredentialListPageResponse:` + + Response containing a paginated list of credentials. + + - `IReadOnlyList Data` + + List of credentials. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + + - `string? NextPage` + + Pagination token for the next page, or null if no more results. + +### Example + +```csharp +CredentialListParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var page = await client.Beta.Vaults.Credentials.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Retrieve(CredentialRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `CredentialRetrieveParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialRetrieveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` + +## Update + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Update(CredentialUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `CredentialUpdateParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `Auth auth` + + Body param: Updated authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthUpdateParams:` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `string? AccessToken` + + Updated OAuth access token. + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshUpdateParams? Refresh` + + Parameters for updating OAuth refresh token configuration. + + - `string? RefreshToken` + + Updated OAuth refresh token. + + - `string? Scope` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth TokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams:` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `string? Token` + + Updated static bearer token value. + + - `string? displayName` + + Body param: Updated human-readable name for the credential. 1-255 characters. + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialUpdateParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Update(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` + +## Delete + +`BetaManagedAgentsDeletedCredential Beta.Vaults.Credentials.Delete(CredentialDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `CredentialDeleteParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeletedCredential:` + + Confirmation of a deleted credential. + + - `required string ID` + + Unique identifier of the deleted credential. + + - `required Type Type` + + - `"vault_credential_deleted"VaultCredentialDeleted` + +### Example + +```csharp +CredentialDeleteParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsDeletedCredential = await client.Beta.Vaults.Credentials.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeletedCredential); +``` + +## Archive + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Archive(CredentialArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `CredentialArchiveParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialArchiveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Archive(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `class BetaManagedAgentsDeletedCredential:` + + Confirmation of a deleted credential. + + - `required string ID` + + Unique identifier of the deleted credential. + + - `required Type Type` + + - `"vault_credential_deleted"VaultCredentialDeleted` + +### Beta Managed Agents MCP OAuth Auth Response + +- `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `class BetaManagedAgentsMcpOAuthCreateParams:` + + Parameters for creating an MCP OAuth credential. + + - `required string AccessToken` + + OAuth access token. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshParams? Refresh` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `required string ClientID` + + OAuth client ID. + + - `required string RefreshToken` + + OAuth refresh token. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `class BetaManagedAgentsMcpOAuthRefreshParams:` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `required string ClientID` + + OAuth client ID. + + - `required string RefreshToken` + + OAuth refresh token. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `class BetaManagedAgentsMcpOAuthRefreshResponse:` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `class BetaManagedAgentsMcpOAuthRefreshUpdateParams:` + + Parameters for updating OAuth refresh token configuration. + + - `string? RefreshToken` + + Updated OAuth refresh token. + + - `string? Scope` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth TokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `class BetaManagedAgentsMcpOAuthUpdateParams:` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `string? AccessToken` + + Updated OAuth access token. + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshUpdateParams? Refresh` + + Parameters for updating OAuth refresh token configuration. + + - `string? RefreshToken` + + Updated OAuth refresh token. + + - `string? Scope` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth TokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + +### Beta Managed Agents Static Bearer Create Params + +- `class BetaManagedAgentsStaticBearerCreateParams:` + + Parameters for creating a static bearer token credential. + + - `required string Token` + + Static bearer token value. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + +### Beta Managed Agents Static Bearer Update Params + +- `class BetaManagedAgentsStaticBearerUpdateParams:` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `string? Token` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. diff --git a/content/en/api/csharp/beta/vaults/archive.md b/content/en/api/csharp/beta/vaults/archive.md new file mode 100644 index 000000000..f6c915989 --- /dev/null +++ b/content/en/api/csharp/beta/vaults/archive.md @@ -0,0 +1,108 @@ +## Archive + +`BetaManagedAgentsVault Beta.Vaults.Archive(VaultArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `VaultArchiveParams parameters` + + - `required string vaultID` + + Path parameter vault_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +VaultArchiveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var betaManagedAgentsVault = await client.Beta.Vaults.Archive(parameters); + +Console.WriteLine(betaManagedAgentsVault); +``` diff --git a/content/en/api/csharp/beta/vaults/create.md b/content/en/api/csharp/beta/vaults/create.md new file mode 100644 index 000000000..8303effac --- /dev/null +++ b/content/en/api/csharp/beta/vaults/create.md @@ -0,0 +1,109 @@ +## Create + +`BetaManagedAgentsVault Beta.Vaults.Create(VaultCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `VaultCreateParams parameters` + + - `required string displayName` + + Body param: Human-readable name for the vault. 1-255 characters. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata to attach to the vault. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +VaultCreateParams parameters = new() { DisplayName = "Example vault" }; + +var betaManagedAgentsVault = await client.Beta.Vaults.Create(parameters); + +Console.WriteLine(betaManagedAgentsVault); +``` diff --git a/content/en/api/csharp/beta/vaults/credentials.md b/content/en/api/csharp/beta/vaults/credentials.md new file mode 100644 index 000000000..789739117 --- /dev/null +++ b/content/en/api/csharp/beta/vaults/credentials.md @@ -0,0 +1,1927 @@ +# Credentials + +## Create + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Create(CredentialCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `CredentialCreateParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required Auth auth` + + Body param: Authentication details for creating a credential. + + - `class BetaManagedAgentsMcpOAuthCreateParams:` + + Parameters for creating an MCP OAuth credential. + + - `required string AccessToken` + + OAuth access token. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshParams? Refresh` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `required string ClientID` + + OAuth client ID. + + - `required string RefreshToken` + + OAuth refresh token. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams:` + + Parameters for creating a static bearer token credential. + + - `required string Token` + + Static bearer token value. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `string? displayName` + + Body param: Human-readable name for the credential. Up to 255 characters. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata to attach to the credential. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialCreateParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + Auth = new BetaManagedAgentsStaticBearerCreateParams() + { + Token = "bearer_exampletoken", + McpServerUrl = "https://example-server.modelcontextprotocol.io/sse", + Type = Type.StaticBearer, + }, +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Create(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` + +## List + +`CredentialListPageResponse Beta.Vaults.Credentials.List(CredentialListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `CredentialListParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `Boolean includeArchived` + + Query param: Whether to include archived credentials in the results. + + - `Int limit` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `string page` + + Query param: Opaque pagination token from a previous `list_credentials` response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class CredentialListPageResponse:` + + Response containing a paginated list of credentials. + + - `IReadOnlyList Data` + + List of credentials. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + + - `string? NextPage` + + Pagination token for the next page, or null if no more results. + +### Example + +```csharp +CredentialListParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var page = await client.Beta.Vaults.Credentials.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` + +## Retrieve + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Retrieve(CredentialRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `CredentialRetrieveParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialRetrieveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` + +## Update + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Update(CredentialUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `CredentialUpdateParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `Auth auth` + + Body param: Updated authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthUpdateParams:` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `string? AccessToken` + + Updated OAuth access token. + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshUpdateParams? Refresh` + + Parameters for updating OAuth refresh token configuration. + + - `string? RefreshToken` + + Updated OAuth refresh token. + + - `string? Scope` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth TokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams:` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `string? Token` + + Updated static bearer token value. + + - `string? displayName` + + Body param: Updated human-readable name for the credential. 1-255 characters. + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialUpdateParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Update(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` + +## Delete + +`BetaManagedAgentsDeletedCredential Beta.Vaults.Credentials.Delete(CredentialDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `CredentialDeleteParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeletedCredential:` + + Confirmation of a deleted credential. + + - `required string ID` + + Unique identifier of the deleted credential. + + - `required Type Type` + + - `"vault_credential_deleted"VaultCredentialDeleted` + +### Example + +```csharp +CredentialDeleteParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsDeletedCredential = await client.Beta.Vaults.Credentials.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeletedCredential); +``` + +## Archive + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Archive(CredentialArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `CredentialArchiveParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialArchiveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Archive(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `class BetaManagedAgentsDeletedCredential:` + + Confirmation of a deleted credential. + + - `required string ID` + + Unique identifier of the deleted credential. + + - `required Type Type` + + - `"vault_credential_deleted"VaultCredentialDeleted` + +### Beta Managed Agents MCP OAuth Auth Response + +- `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `class BetaManagedAgentsMcpOAuthCreateParams:` + + Parameters for creating an MCP OAuth credential. + + - `required string AccessToken` + + OAuth access token. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshParams? Refresh` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `required string ClientID` + + OAuth client ID. + + - `required string RefreshToken` + + OAuth refresh token. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `class BetaManagedAgentsMcpOAuthRefreshParams:` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `required string ClientID` + + OAuth client ID. + + - `required string RefreshToken` + + OAuth refresh token. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `class BetaManagedAgentsMcpOAuthRefreshResponse:` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `class BetaManagedAgentsMcpOAuthRefreshUpdateParams:` + + Parameters for updating OAuth refresh token configuration. + + - `string? RefreshToken` + + Updated OAuth refresh token. + + - `string? Scope` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth TokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `class BetaManagedAgentsMcpOAuthUpdateParams:` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `string? AccessToken` + + Updated OAuth access token. + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshUpdateParams? Refresh` + + Parameters for updating OAuth refresh token configuration. + + - `string? RefreshToken` + + Updated OAuth refresh token. + + - `string? Scope` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth TokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + +### Beta Managed Agents Static Bearer Create Params + +- `class BetaManagedAgentsStaticBearerCreateParams:` + + Parameters for creating a static bearer token credential. + + - `required string Token` + + Static bearer token value. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + +### Beta Managed Agents Static Bearer Update Params + +- `class BetaManagedAgentsStaticBearerUpdateParams:` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `string? Token` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. diff --git a/content/en/api/csharp/beta/vaults/credentials/archive.md b/content/en/api/csharp/beta/vaults/credentials/archive.md new file mode 100644 index 000000000..ace12a612 --- /dev/null +++ b/content/en/api/csharp/beta/vaults/credentials/archive.md @@ -0,0 +1,197 @@ +## Archive + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Archive(CredentialArchiveParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `CredentialArchiveParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialArchiveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Archive(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` diff --git a/content/en/api/csharp/beta/vaults/credentials/create.md b/content/en/api/csharp/beta/vaults/credentials/create.md new file mode 100644 index 000000000..5dff94cc7 --- /dev/null +++ b/content/en/api/csharp/beta/vaults/credentials/create.md @@ -0,0 +1,306 @@ +## Create + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Create(CredentialCreateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `CredentialCreateParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required Auth auth` + + Body param: Authentication details for creating a credential. + + - `class BetaManagedAgentsMcpOAuthCreateParams:` + + Parameters for creating an MCP OAuth credential. + + - `required string AccessToken` + + OAuth access token. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshParams? Refresh` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `required string ClientID` + + OAuth client ID. + + - `required string RefreshToken` + + OAuth refresh token. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `required string ClientSecret` + + OAuth client secret. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams:` + + Parameters for creating a static bearer token credential. + + - `required string Token` + + Static bearer token value. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `string? displayName` + + Body param: Human-readable name for the credential. Up to 255 characters. + + - `IReadOnlyDictionary metadata` + + Body param: Arbitrary key-value metadata to attach to the credential. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialCreateParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + Auth = new BetaManagedAgentsStaticBearerCreateParams() + { + Token = "bearer_exampletoken", + McpServerUrl = "https://example-server.modelcontextprotocol.io/sse", + Type = Type.StaticBearer, + }, +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Create(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` diff --git a/content/en/api/csharp/beta/vaults/credentials/delete.md b/content/en/api/csharp/beta/vaults/credentials/delete.md new file mode 100644 index 000000000..c70045b4f --- /dev/null +++ b/content/en/api/csharp/beta/vaults/credentials/delete.md @@ -0,0 +1,93 @@ +## Delete + +`BetaManagedAgentsDeletedCredential Beta.Vaults.Credentials.Delete(CredentialDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `CredentialDeleteParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeletedCredential:` + + Confirmation of a deleted credential. + + - `required string ID` + + Unique identifier of the deleted credential. + + - `required Type Type` + + - `"vault_credential_deleted"VaultCredentialDeleted` + +### Example + +```csharp +CredentialDeleteParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsDeletedCredential = await client.Beta.Vaults.Credentials.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeletedCredential); +``` diff --git a/content/en/api/csharp/beta/vaults/credentials/list.md b/content/en/api/csharp/beta/vaults/credentials/list.md new file mode 100644 index 000000000..675566e31 --- /dev/null +++ b/content/en/api/csharp/beta/vaults/credentials/list.md @@ -0,0 +1,214 @@ +## List + +`CredentialListPageResponse Beta.Vaults.Credentials.List(CredentialListParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `CredentialListParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `Boolean includeArchived` + + Query param: Whether to include archived credentials in the results. + + - `Int limit` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `string page` + + Query param: Opaque pagination token from a previous `list_credentials` response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class CredentialListPageResponse:` + + Response containing a paginated list of credentials. + + - `IReadOnlyList Data` + + List of credentials. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + + - `string? NextPage` + + Pagination token for the next page, or null if no more results. + +### Example + +```csharp +CredentialListParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var page = await client.Beta.Vaults.Credentials.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` diff --git a/content/en/api/csharp/beta/vaults/credentials/retrieve.md b/content/en/api/csharp/beta/vaults/credentials/retrieve.md new file mode 100644 index 000000000..1d26c7d07 --- /dev/null +++ b/content/en/api/csharp/beta/vaults/credentials/retrieve.md @@ -0,0 +1,197 @@ +## Retrieve + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Retrieve(CredentialRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `CredentialRetrieveParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialRetrieveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` diff --git a/content/en/api/csharp/beta/vaults/credentials/update.md b/content/en/api/csharp/beta/vaults/credentials/update.md new file mode 100644 index 000000000..180dafff6 --- /dev/null +++ b/content/en/api/csharp/beta/vaults/credentials/update.md @@ -0,0 +1,277 @@ +## Update + +`BetaManagedAgentsCredential Beta.Vaults.Credentials.Update(CredentialUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `CredentialUpdateParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `required string credentialID` + + Path param: Path parameter credential_id + + - `Auth auth` + + Body param: Updated authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthUpdateParams:` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `string? AccessToken` + + Updated OAuth access token. + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshUpdateParams? Refresh` + + Parameters for updating OAuth refresh token configuration. + + - `string? RefreshToken` + + Updated OAuth refresh token. + + - `string? Scope` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth TokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? ClientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams:` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `string? Token` + + Updated static bearer token value. + + - `string? displayName` + + Body param: Updated human-readable name for the credential. 1-255 characters. + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `required string ID` + + Unique identifier for the credential. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required Auth Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"mcp_oauth"McpOAuth` + + - `DateTimeOffset? ExpiresAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsMcpOAuthRefreshResponse? Refresh` + + OAuth refresh token configuration returned in credential responses. + + - `required string ClientID` + + OAuth client ID. + + - `required string TokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `required TokenEndpointAuth TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `required Type Type` + + - `"none"None` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `required Type Type` + + - `"client_secret_basic"ClientSecretBasic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `required Type Type` + + - `"client_secret_post"ClientSecretPost` + + - `string? Resource` + + OAuth resource indicator. + + - `string? Scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `required string McpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `required Type Type` + + - `"static_bearer"StaticBearer` + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the credential. + + - `required Type Type` + + - `"vault_credential"VaultCredential` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `required string VaultID` + + Identifier of the vault this credential belongs to. + + - `string? DisplayName` + + Human-readable name for the credential. + +### Example + +```csharp +CredentialUpdateParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv", + CredentialID = "vcrd_011CZkZEMt8gZan2iYOQfSkw", +}; + +var betaManagedAgentsCredential = await client.Beta.Vaults.Credentials.Update(parameters); + +Console.WriteLine(betaManagedAgentsCredential); +``` diff --git a/content/en/api/csharp/beta/vaults/delete.md b/content/en/api/csharp/beta/vaults/delete.md new file mode 100644 index 000000000..fd4704022 --- /dev/null +++ b/content/en/api/csharp/beta/vaults/delete.md @@ -0,0 +1,88 @@ +## Delete + +`BetaManagedAgentsDeletedVault Beta.Vaults.Delete(VaultDeleteParamsparameters, CancellationTokencancellationToken = default)` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `VaultDeleteParams parameters` + + - `required string vaultID` + + Path parameter vault_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsDeletedVault:` + + Confirmation of a deleted vault. + + - `required string ID` + + Unique identifier of the deleted vault. + + - `required Type Type` + + - `"vault_deleted"VaultDeleted` + +### Example + +```csharp +VaultDeleteParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var betaManagedAgentsDeletedVault = await client.Beta.Vaults.Delete(parameters); + +Console.WriteLine(betaManagedAgentsDeletedVault); +``` diff --git a/content/en/api/csharp/beta/vaults/list.md b/content/en/api/csharp/beta/vaults/list.md new file mode 100644 index 000000000..ed95544eb --- /dev/null +++ b/content/en/api/csharp/beta/vaults/list.md @@ -0,0 +1,123 @@ +## List + +`VaultListPageResponse Beta.Vaults.List(VaultListParams?parameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `VaultListParams parameters` + + - `Boolean includeArchived` + + Query param: Whether to include archived vaults in the results. + + - `Int limit` + + Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. + + - `string page` + + Query param: Opaque pagination token from a previous `list_vaults` response. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class VaultListPageResponse:` + + Response containing a paginated list of vaults. + + - `IReadOnlyList Data` + + List of vaults. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + + - `string? NextPage` + + Pagination token for the next page, or null if no more results. + +### Example + +```csharp +VaultListParams parameters = new(); + +var page = await client.Beta.Vaults.List(parameters); +await foreach (var item in page.Paginate()) +{ + Console.WriteLine(item); +} +``` diff --git a/content/en/api/csharp/beta/vaults/retrieve.md b/content/en/api/csharp/beta/vaults/retrieve.md new file mode 100644 index 000000000..1bee36a46 --- /dev/null +++ b/content/en/api/csharp/beta/vaults/retrieve.md @@ -0,0 +1,108 @@ +## Retrieve + +`BetaManagedAgentsVault Beta.Vaults.Retrieve(VaultRetrieveParamsparameters, CancellationTokencancellationToken = default)` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `VaultRetrieveParams parameters` + + - `required string vaultID` + + Path parameter vault_id + + - `IReadOnlyList betas` + + Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +VaultRetrieveParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var betaManagedAgentsVault = await client.Beta.Vaults.Retrieve(parameters); + +Console.WriteLine(betaManagedAgentsVault); +``` diff --git a/content/en/api/csharp/beta/vaults/update.md b/content/en/api/csharp/beta/vaults/update.md new file mode 100644 index 000000000..9256d8dd5 --- /dev/null +++ b/content/en/api/csharp/beta/vaults/update.md @@ -0,0 +1,116 @@ +## Update + +`BetaManagedAgentsVault Beta.Vaults.Update(VaultUpdateParamsparameters, CancellationTokencancellationToken = default)` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `VaultUpdateParams parameters` + + - `required string vaultID` + + Path param: Path parameter vault_id + + - `string? displayName` + + Body param: Updated human-readable name for the vault. 1-255 characters. + + - `IReadOnlyDictionary? metadata` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `IReadOnlyList betas` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `"message-batches-2024-09-24"MessageBatches2024_09_24` + + - `"prompt-caching-2024-07-31"PromptCaching2024_07_31` + + - `"computer-use-2024-10-22"ComputerUse2024_10_22` + + - `"computer-use-2025-01-24"ComputerUse2025_01_24` + + - `"pdfs-2024-09-25"Pdfs2024_09_25` + + - `"token-counting-2024-11-01"TokenCounting2024_11_01` + + - `"token-efficient-tools-2025-02-19"TokenEfficientTools2025_02_19` + + - `"output-128k-2025-02-19"Output128k2025_02_19` + + - `"files-api-2025-04-14"FilesApi2025_04_14` + + - `"mcp-client-2025-04-04"McpClient2025_04_04` + + - `"mcp-client-2025-11-20"McpClient2025_11_20` + + - `"dev-full-thinking-2025-05-14"DevFullThinking2025_05_14` + + - `"interleaved-thinking-2025-05-14"InterleavedThinking2025_05_14` + + - `"code-execution-2025-05-22"CodeExecution2025_05_22` + + - `"extended-cache-ttl-2025-04-11"ExtendedCacheTtl2025_04_11` + + - `"context-1m-2025-08-07"Context1m2025_08_07` + + - `"context-management-2025-06-27"ContextManagement2025_06_27` + + - `"model-context-window-exceeded-2025-08-26"ModelContextWindowExceeded2025_08_26` + + - `"skills-2025-10-02"Skills2025_10_02` + + - `"fast-mode-2026-02-01"FastMode2026_02_01` + + - `"output-300k-2026-03-24"Output300k2026_03_24` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `required string ID` + + Unique identifier for the vault. + + - `required DateTimeOffset? ArchivedAt` + + A timestamp in RFC 3339 format + + - `required DateTimeOffset CreatedAt` + + A timestamp in RFC 3339 format + + - `required string DisplayName` + + Human-readable name for the vault. + + - `required IReadOnlyDictionary Metadata` + + Arbitrary key-value metadata attached to the vault. + + - `required Type Type` + + - `"vault"Vault` + + - `required DateTimeOffset UpdatedAt` + + A timestamp in RFC 3339 format + +### Example + +```csharp +VaultUpdateParams parameters = new() +{ + VaultID = "vlt_011CZkZDLs7fYzm1hXNPeRjv" +}; + +var betaManagedAgentsVault = await client.Beta.Vaults.Update(parameters); + +Console.WriteLine(betaManagedAgentsVault); +``` diff --git a/content/en/api/csharp/messages.md b/content/en/api/csharp/messages.md index 7afe48264..24cdfbdd2 100644 --- a/content/en/api/csharp/messages.md +++ b/content/en/api/csharp/messages.md @@ -3795,9 +3795,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -7157,7 +7161,7 @@ MessageCountTokensParams parameters = new() Role = Role.User, }, ], - Model = Model.ClaudeOpus4_6, + Model = Model.ClaudeMythosPreview, }; var messageTokensCount = await client.Messages.CountTokens(parameters); @@ -12055,9 +12059,13 @@ Console.WriteLine(messageTokensCount); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -16709,9 +16717,13 @@ Console.WriteLine(messageTokensCount); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -17521,9 +17533,13 @@ Console.WriteLine(messageTokensCount); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -25504,9 +25520,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -28161,9 +28181,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -29250,9 +29274,13 @@ await foreach (var messageBatchIndividualResponse in client.Messages.Batches.Res See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -30166,9 +30194,13 @@ await foreach (var messageBatchIndividualResponse in client.Messages.Batches.Res See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -31044,9 +31076,13 @@ await foreach (var messageBatchIndividualResponse in client.Messages.Batches.Res See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` diff --git a/content/en/api/csharp/messages/batches.md b/content/en/api/csharp/messages/batches.md index 042d7258a..b6984ccdf 100644 --- a/content/en/api/csharp/messages/batches.md +++ b/content/en/api/csharp/messages/batches.md @@ -2017,9 +2017,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -4674,9 +4678,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -5763,9 +5771,13 @@ await foreach (var messageBatchIndividualResponse in client.Messages.Batches.Res See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -6679,9 +6691,13 @@ await foreach (var messageBatchIndividualResponse in client.Messages.Batches.Res See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` @@ -7557,9 +7573,13 @@ await foreach (var messageBatchIndividualResponse in client.Messages.Batches.Res See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` diff --git a/content/en/api/csharp/messages/batches/create.md b/content/en/api/csharp/messages/batches/create.md index 45b2ca55f..e2821d1ae 100644 --- a/content/en/api/csharp/messages/batches/create.md +++ b/content/en/api/csharp/messages/batches/create.md @@ -2015,9 +2015,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` diff --git a/content/en/api/csharp/messages/batches/results.md b/content/en/api/csharp/messages/batches/results.md index f4be58ea3..d900a75ab 100644 --- a/content/en/api/csharp/messages/batches/results.md +++ b/content/en/api/csharp/messages/batches/results.md @@ -643,9 +643,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` diff --git a/content/en/api/csharp/messages/count_tokens.md b/content/en/api/csharp/messages/count_tokens.md index 40dd7ca72..fde49266f 100644 --- a/content/en/api/csharp/messages/count_tokens.md +++ b/content/en/api/csharp/messages/count_tokens.md @@ -3145,7 +3145,7 @@ MessageCountTokensParams parameters = new() Role = Role.User, }, ], - Model = Model.ClaudeOpus4_6, + Model = Model.ClaudeMythosPreview, }; var messageTokensCount = await client.Messages.CountTokens(parameters); diff --git a/content/en/api/csharp/messages/create.md b/content/en/api/csharp/messages/create.md index bb797667e..238964b4b 100644 --- a/content/en/api/csharp/messages/create.md +++ b/content/en/api/csharp/messages/create.md @@ -3793,9 +3793,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"ClaudeMythosPreview` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"ClaudeOpus4_6` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"ClaudeSonnet4_6` diff --git a/content/en/api/csharp/models.md b/content/en/api/csharp/models.md index 019b011a8..ed1e922e3 100644 --- a/content/en/api/csharp/models.md +++ b/content/en/api/csharp/models.md @@ -74,8 +74,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class ModelListPageResponse:` @@ -348,8 +346,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class ModelInfo:` diff --git a/content/en/api/csharp/models/list.md b/content/en/api/csharp/models/list.md index c7e5767cc..7ca0967ba 100644 --- a/content/en/api/csharp/models/list.md +++ b/content/en/api/csharp/models/list.md @@ -72,8 +72,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class ModelListPageResponse:` diff --git a/content/en/api/csharp/models/retrieve.md b/content/en/api/csharp/models/retrieve.md index 006d3be5f..bbd6bac08 100644 --- a/content/en/api/csharp/models/retrieve.md +++ b/content/en/api/csharp/models/retrieve.md @@ -62,8 +62,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"Output300k2026_03_24` - - `"user-profiles-2026-03-24"UserProfiles2026_03_24` - ### Returns - `class ModelInfo:` diff --git a/content/en/api/errors.md b/content/en/api/errors.md index 41ab7bf23..9a9fee83c 100644 --- a/content/en/api/errors.md +++ b/content/en/api/errors.md @@ -62,6 +62,14 @@ Every API response includes a unique `request-id` header. This header contains a The official SDKs provide this value as a property on top-level response objects, containing the value of the `request-id` header: + ```bash CLI + # The request-id header is printed to stderr with --debug: + ant --debug messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --message '{role: user, content: "Hello, Claude"}' + ``` + ```python Python hidelines={1..2} import anthropic diff --git a/content/en/api/go/beta.md b/content/en/api/go/beta.md index 3fc56ff41..b6784a6aa 100644 --- a/content/en/api/go/beta.md +++ b/content/en/api/go/beta.md @@ -52,8 +52,6 @@ - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Beta API Error - `type BetaAPIError struct{…}` @@ -384,8 +382,6 @@ The Models API response can be used to determine which models are available for - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaModelInfo struct{…}` @@ -665,8 +661,6 @@ The Models API response can be used to determine information about a specific mo - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaModelInfo struct{…}` @@ -5693,10 +5687,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. - - `UserProfileID param.Field[string]` - - Body param: The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `Betas param.Field[[]AnthropicBeta]` Header param: Optional header to specify the beta version(s) you want to use. @@ -5747,8 +5737,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessage struct{…}` @@ -6678,9 +6666,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -11302,8 +11294,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageTokensCount struct{…}` @@ -11346,7 +11336,7 @@ func main() { }}, Role: anthropic.BetaMessageParamRoleUser, }}, - Model: anthropic.ModelClaudeOpus4_6, + Model: anthropic.ModelClaudeMythosPreview, }) if err != nil { panic(err.Error()) @@ -18544,9 +18534,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -23884,9 +23878,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -25128,9 +25126,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -36264,9 +36266,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -38333,10 +38339,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `UserProfileID string` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `Betas param.Field[[]AnthropicBeta]` Header param: Optional header to specify the beta version(s) you want to use. @@ -38387,8 +38389,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` @@ -38588,8 +38588,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` @@ -38789,8 +38787,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` @@ -38978,8 +38974,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` @@ -39171,8 +39165,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaDeletedMessageBatch struct{…}` @@ -39290,8 +39282,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatchIndividualResponse struct{…}` @@ -40239,9 +40229,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -41837,9 +41831,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -43209,9 +43207,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -44543,9 +44545,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -44846,305 +44852,347 @@ func main() { - `const SucceededSucceeded Succeeded = "succeeded"` -# Files +# Agents -## Upload +## Create -`client.Beta.Files.Upload(ctx, params) (*FileMetadata, error)` +`client.Beta.Agents.New(ctx, params) (*BetaManagedAgentsAgent, error)` -**post** `/v1/files` +**post** `/v1/agents` -Upload File +Create Agent ### Parameters -- `params BetaFileUploadParams` +- `params BetaAgentNewParams` - - `File param.Field[Reader]` + - `Model param.Field[BetaManagedAgentsModelConfigParamsResp]` - Body param: The file to upload + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control - - `Betas param.Field[[]AnthropicBeta]` + - `type BetaManagedAgentsModelConfigParamsResp struct{…}` - Header param: Optional header to specify the beta version(s) you want to use. + An object that defines additional configuration control over model use - - `string` + - `ID BetaManagedAgentsModel` - - `type AnthropicBeta string` + The model that will power your agent. - - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + - `type BetaManagedAgentsModel string` - - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + The model that will power your agent. - - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` - - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + Most intelligent model for building agents and coding - - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` - - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + Best combination of speed and intelligence - - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` - - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + Fastest model with near-frontier intelligence - - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` - - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + Fastest model with near-frontier intelligence - - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` - - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + Premium model combining maximum intelligence with practical performance - - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` - - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + Premium model combining maximum intelligence with practical performance - - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` - - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + High-performance model for agents and coding - - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` - - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + High-performance model for agents and coding - - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + - `string` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` + - `Speed BetaManagedAgentsModelConfigParamsSpeed` -### Returns + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. -- `type FileMetadata struct{…}` + - `const BetaManagedAgentsModelConfigParamsSpeedStandard BetaManagedAgentsModelConfigParamsSpeed = "standard"` - - `ID string` + - `const BetaManagedAgentsModelConfigParamsSpeedFast BetaManagedAgentsModelConfigParamsSpeed = "fast"` - Unique object identifier. + - `Name param.Field[string]` - The format and length of IDs may change over time. + Body param: Human-readable name for the agent. 1-256 characters. - - `CreatedAt Time` + - `Description param.Field[string]` - RFC 3339 datetime string representing when the file was created. + Body param: Description of what the agent does. Up to 2048 characters. - - `Filename string` + - `MCPServers param.Field[[]BetaManagedAgentsURLMCPServerParamsResp]` - Original filename of the uploaded file. + Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. - - `MimeType string` + - `Name string` - MIME type of the file. + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. - - `SizeBytes int64` + - `Type BetaManagedAgentsURLMCPServerParamsType` - Size of the file in bytes. + - `const BetaManagedAgentsURLMCPServerParamsTypeURL BetaManagedAgentsURLMCPServerParamsType = "url"` - - `Type File` + - `URL string` - Object type. + Endpoint URL for the MCP server. - For files, this is always `"file"`. + - `Metadata param.Field[map[string, string]]` - - `const FileFile File = "file"` + Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - - `Downloadable bool` + - `Skills param.Field[[]BetaManagedAgentsSkillParamsUnionResp]` - Whether the file can be downloaded. + Body param: Skills available to the agent. Maximum 20. -### Example + - `type BetaManagedAgentsAnthropicSkillParamsResp struct{…}` -```go -package main + An Anthropic-managed skill. -import ( - "bytes" - "context" - "fmt" - "io" + - `SkillID string` - "github.com/anthropics/anthropic-sdk-go" - "github.com/anthropics/anthropic-sdk-go/option" -) + Identifier of the Anthropic skill (e.g., "xlsx"). -func main() { - client := anthropic.NewClient( - option.WithAPIKey("my-anthropic-api-key"), - ) - fileMetadata, err := client.Beta.Files.Upload(context.TODO(), anthropic.BetaFileUploadParams{ - File: io.Reader(bytes.NewBuffer([]byte("Example data"))), - }) - if err != nil { - panic(err.Error()) - } - fmt.Printf("%+v\n", fileMetadata.ID) -} -``` + - `Type BetaManagedAgentsAnthropicSkillParamsType` -## List + - `const BetaManagedAgentsAnthropicSkillParamsTypeAnthropic BetaManagedAgentsAnthropicSkillParamsType = "anthropic"` -`client.Beta.Files.List(ctx, params) (*Page[FileMetadata], error)` + - `Version string` -**get** `/v1/files` + Version to pin. Defaults to latest if omitted. -List Files + - `type BetaManagedAgentsCustomSkillParamsResp struct{…}` -### Parameters + A user-created custom skill. -- `params BetaFileListParams` + - `SkillID string` - - `AfterID param.Field[string]` + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). - Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + - `Type BetaManagedAgentsCustomSkillParamsType` - - `BeforeID param.Field[string]` + - `const BetaManagedAgentsCustomSkillParamsTypeCustom BetaManagedAgentsCustomSkillParamsType = "custom"` - Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + - `Version string` - - `Limit param.Field[int64]` + Version to pin. Defaults to latest if omitted. - Query param: Number of items to return per page. + - `System param.Field[string]` - Defaults to `20`. Ranges from `1` to `1000`. + Body param: System prompt for the agent. Up to 100,000 characters. - - `Betas param.Field[[]AnthropicBeta]` + - `Tools param.Field[[]BetaAgentNewParamsToolUnion]` - Header param: Optional header to specify the beta version(s) you want to use. + Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. - - `string` + - `type BetaManagedAgentsAgentToolset20260401ParamsResp struct{…}` - - `type AnthropicBeta string` + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. - - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + - `Type BetaManagedAgentsAgentToolset20260401ParamsType` - - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + - `const BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401ParamsType = "agent_toolset_20260401"` - - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + - `Configs []BetaManagedAgentsAgentToolConfigParamsResp` - - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + Per-tool configuration overrides. - - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + - `Name BetaManagedAgentsAgentToolConfigParamsName` - - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + Built-in agent tool identifier. - - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + - `const BetaManagedAgentsAgentToolConfigParamsNameBash BetaManagedAgentsAgentToolConfigParamsName = "bash"` - - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + - `const BetaManagedAgentsAgentToolConfigParamsNameEdit BetaManagedAgentsAgentToolConfigParamsName = "edit"` - - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + - `const BetaManagedAgentsAgentToolConfigParamsNameRead BetaManagedAgentsAgentToolConfigParamsName = "read"` - - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + - `const BetaManagedAgentsAgentToolConfigParamsNameWrite BetaManagedAgentsAgentToolConfigParamsName = "write"` - - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + - `const BetaManagedAgentsAgentToolConfigParamsNameGlob BetaManagedAgentsAgentToolConfigParamsName = "glob"` - - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + - `const BetaManagedAgentsAgentToolConfigParamsNameGrep BetaManagedAgentsAgentToolConfigParamsName = "grep"` - - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + - `const BetaManagedAgentsAgentToolConfigParamsNameWebFetch BetaManagedAgentsAgentToolConfigParamsName = "web_fetch"` - - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + - `const BetaManagedAgentsAgentToolConfigParamsNameWebSearch BetaManagedAgentsAgentToolConfigParamsName = "web_search"` - - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + - `Enabled bool` - - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + Whether this tool is enabled and available to Claude. Overrides the default_config setting. - - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + - `PermissionPolicy BetaManagedAgentsAgentToolConfigParamsPermissionPolicyUnionResp` - - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + Permission policy for tool execution. - - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` - - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + Tool calls are automatically approved without user confirmation. - - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + - `Type BetaManagedAgentsAlwaysAllowPolicyType` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` -### Returns + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` -- `type FileMetadata struct{…}` + Tool calls require user confirmation before execution. - - `ID string` + - `Type BetaManagedAgentsAlwaysAskPolicyType` - Unique object identifier. + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` - The format and length of IDs may change over time. + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfigParamsResp` - - `CreatedAt Time` + Default configuration for all tools in a toolset. - RFC 3339 datetime string representing when the file was created. + - `Enabled bool` - - `Filename string` + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - Original filename of the uploaded file. + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnionResp` - - `MimeType string` + Permission policy for tool execution. - MIME type of the file. + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` - - `SizeBytes int64` + Tool calls are automatically approved without user confirmation. - Size of the file in bytes. + - `Type BetaManagedAgentsAlwaysAllowPolicyType` - - `Type File` + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` - Object type. + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` - For files, this is always `"file"`. + Tool calls require user confirmation before execution. - - `const FileFile File = "file"` + - `Type BetaManagedAgentsAlwaysAskPolicyType` - - `Downloadable bool` + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` - Whether the file can be downloaded. + - `type BetaManagedAgentsMCPToolsetParamsResp struct{…}` -### Example + Configuration for tools from an MCP server defined in `mcp_servers`. -```go -package main + - `MCPServerName string` -import ( - "context" - "fmt" + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. - "github.com/anthropics/anthropic-sdk-go" - "github.com/anthropics/anthropic-sdk-go/option" -) + - `Type BetaManagedAgentsMCPToolsetParamsType` -func main() { - client := anthropic.NewClient( - option.WithAPIKey("my-anthropic-api-key"), - ) - page, err := client.Beta.Files.List(context.TODO(), anthropic.BetaFileListParams{ + - `const BetaManagedAgentsMCPToolsetParamsTypeMCPToolset BetaManagedAgentsMCPToolsetParamsType = "mcp_toolset"` - }) - if err != nil { - panic(err.Error()) - } - fmt.Printf("%+v\n", page) -} -``` + - `Configs []BetaManagedAgentsMCPToolConfigParamsResp` -## Download + Per-tool configuration overrides. -`client.Beta.Files.Download(ctx, fileID, query) (*Response, error)` + - `Name string` -**get** `/v1/files/{file_id}/content` + Name of the MCP tool to configure. 1-128 characters. -Download File + - `Enabled bool` -### Parameters + Whether this tool is enabled. Overrides the `default_config` setting. -- `fileID string` + - `PermissionPolicy BetaManagedAgentsMCPToolConfigParamsPermissionPolicyUnionResp` - ID of the File. + Permission policy for tool execution. -- `query BetaFileDownloadParams` + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfigParamsResp` + + Default configuration for all tools from an MCP server. + + - `Enabled bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `type BetaManagedAgentsCustomToolParamsResp struct{…}` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `Description string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `Type BetaManagedAgentsCustomToolParamsType` + + - `const BetaManagedAgentsCustomToolParamsTypeCustom BetaManagedAgentsCustomToolParamsType = "custom"` - `Betas param.Field[[]AnthropicBeta]` - Optional header to specify the beta version(s) you want to use. + Header param: Optional header to specify the beta version(s) you want to use. - `string` @@ -45192,11 +45240,303 @@ Download File - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaFileDownloadResponse interface{…}` +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. ### Example @@ -45215,39 +45555,54 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - response, err := client.Beta.Files.Download( - context.TODO(), - "file_id", - anthropic.BetaFileDownloadParams{ - + betaManagedAgentsAgent, err := client.Beta.Agents.New(context.TODO(), anthropic.BetaAgentNewParams{ + Model: anthropic.BetaManagedAgentsModelConfigParams{ + ID: anthropic.BetaManagedAgentsModelClaudeOpus4_6, }, - ) + Name: "My First Agent", + }) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", response) + fmt.Printf("%+v\n", betaManagedAgentsAgent.ID) } ``` -## Retrieve Metadata +## List -`client.Beta.Files.GetMetadata(ctx, fileID, query) (*FileMetadata, error)` +`client.Beta.Agents.List(ctx, params) (*PageCursor[BetaManagedAgentsAgent], error)` -**get** `/v1/files/{file_id}` +**get** `/v1/agents` -Get File Metadata +List Agents ### Parameters -- `fileID string` +- `params BetaAgentListParams` - ID of the File. + - `CreatedAtGte param.Field[Time]` -- `query BetaFileGetMetadataParams` + Query param: Return agents created at or after this time (inclusive). + + - `CreatedAtLte param.Field[Time]` + + Query param: Return agents created at or before this time (inclusive). + + - `IncludeArchived param.Field[bool]` + + Query param: Include archived agents in results. Defaults to false. + + - `Limit param.Field[int64]` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor from a previous response. - `Betas param.Field[[]AnthropicBeta]` - Optional header to specify the beta version(s) you want to use. + Header param: Optional header to specify the beta version(s) you want to use. - `string` @@ -45295,45 +45650,303 @@ Get File Metadata - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type FileMetadata struct{…}` +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. - `ID string` - Unique object identifier. + - `ArchivedAt Time` - The format and length of IDs may change over time. + A timestamp in RFC 3339 format - `CreatedAt Time` - RFC 3339 datetime string representing when the file was created. + A timestamp in RFC 3339 format - - `Filename string` + - `Description string` - Original filename of the uploaded file. + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` - - `MimeType string` + - `Name string` - MIME type of the file. + - `Type BetaManagedAgentsMCPServerURLDefinitionType` - - `SizeBytes int64` + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` - Size of the file in bytes. + - `URL string` - - `Type File` + - `Metadata map[string, string]` - Object type. + - `Model BetaManagedAgentsModelConfig` - For files, this is always `"file"`. + Model identifier and configuration. - - `const FileFile File = "file"` + - `ID BetaManagedAgentsModel` - - `Downloadable bool` + The model that will power your agent. - Whether the file can be downloaded. + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. ### Example @@ -45352,39 +45965,37 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - fileMetadata, err := client.Beta.Files.GetMetadata( - context.TODO(), - "file_id", - anthropic.BetaFileGetMetadataParams{ + page, err := client.Beta.Agents.List(context.TODO(), anthropic.BetaAgentListParams{ - }, - ) + }) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", fileMetadata.ID) + fmt.Printf("%+v\n", page) } ``` -## Delete +## Retrieve -`client.Beta.Files.Delete(ctx, fileID, body) (*DeletedFile, error)` +`client.Beta.Agents.Get(ctx, agentID, params) (*BetaManagedAgentsAgent, error)` -**delete** `/v1/files/{file_id}` +**get** `/v1/agents/{agent_id}` -Delete File +Get Agent ### Parameters -- `fileID string` +- `agentID string` - ID of the File. +- `params BetaAgentGetParams` -- `body BetaFileDeleteParams` + - `Version param.Field[int64]` + + Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. - `Betas param.Field[[]AnthropicBeta]` - Optional header to specify the beta version(s) you want to use. + Header param: Optional header to specify the beta version(s) you want to use. - `string` @@ -45416,152 +46027,22066 @@ Delete File - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` - - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsAgent, err := client.Beta.Agents.Get( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentGetParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsAgent.ID) +} +``` + +## Update + +`client.Beta.Agents.Update(ctx, agentID, params) (*BetaManagedAgentsAgent, error)` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `agentID string` + +- `params BetaAgentUpdateParams` + + - `Version param.Field[int64]` + + Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + + - `Description param.Field[string]` + + Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + + - `MCPServers param.Field[[]BetaManagedAgentsURLMCPServerParamsResp]` + + Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `Name string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `Type BetaManagedAgentsURLMCPServerParamsType` + + - `const BetaManagedAgentsURLMCPServerParamsTypeURL BetaManagedAgentsURLMCPServerParamsType = "url"` + + - `URL string` + + Endpoint URL for the MCP server. + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + + - `Model param.Field[BetaManagedAgentsModelConfigParamsResp]` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `type BetaManagedAgentsModelConfigParamsResp struct{…}` + + An object that defines additional configuration control over model use + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigParamsSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigParamsSpeedStandard BetaManagedAgentsModelConfigParamsSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigParamsSpeedFast BetaManagedAgentsModelConfigParamsSpeed = "fast"` + + - `Name param.Field[string]` + + Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + + - `Skills param.Field[[]BetaManagedAgentsSkillParamsUnionResp]` + + Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `type BetaManagedAgentsAnthropicSkillParamsResp struct{…}` + + An Anthropic-managed skill. + + - `SkillID string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `Type BetaManagedAgentsAnthropicSkillParamsType` + + - `const BetaManagedAgentsAnthropicSkillParamsTypeAnthropic BetaManagedAgentsAnthropicSkillParamsType = "anthropic"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + + - `type BetaManagedAgentsCustomSkillParamsResp struct{…}` + + A user-created custom skill. + + - `SkillID string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `Type BetaManagedAgentsCustomSkillParamsType` + + - `const BetaManagedAgentsCustomSkillParamsTypeCustom BetaManagedAgentsCustomSkillParamsType = "custom"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + + - `System param.Field[string]` + + Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + + - `Tools param.Field[[]BetaAgentUpdateParamsToolUnion]` + + Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `type BetaManagedAgentsAgentToolset20260401ParamsResp struct{…}` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `Type BetaManagedAgentsAgentToolset20260401ParamsType` + + - `const BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401ParamsType = "agent_toolset_20260401"` + + - `Configs []BetaManagedAgentsAgentToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name BetaManagedAgentsAgentToolConfigParamsName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigParamsNameBash BetaManagedAgentsAgentToolConfigParamsName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameEdit BetaManagedAgentsAgentToolConfigParamsName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameRead BetaManagedAgentsAgentToolConfigParamsName = "read"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWrite BetaManagedAgentsAgentToolConfigParamsName = "write"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGlob BetaManagedAgentsAgentToolConfigParamsName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGrep BetaManagedAgentsAgentToolConfigParamsName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebFetch BetaManagedAgentsAgentToolConfigParamsName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebSearch BetaManagedAgentsAgentToolConfigParamsName = "web_search"` + + - `Enabled bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfigParamsResp` + + Default configuration for all tools in a toolset. + + - `Enabled bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `type BetaManagedAgentsMCPToolsetParamsResp struct{…}` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `MCPServerName string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `Type BetaManagedAgentsMCPToolsetParamsType` + + - `const BetaManagedAgentsMCPToolsetParamsTypeMCPToolset BetaManagedAgentsMCPToolsetParamsType = "mcp_toolset"` + + - `Configs []BetaManagedAgentsMCPToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name string` + + Name of the MCP tool to configure. 1-128 characters. + + - `Enabled bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfigParamsResp` + + Default configuration for all tools from an MCP server. + + - `Enabled bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `type BetaManagedAgentsCustomToolParamsResp struct{…}` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `Description string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `Type BetaManagedAgentsCustomToolParamsType` + + - `const BetaManagedAgentsCustomToolParamsTypeCustom BetaManagedAgentsCustomToolParamsType = "custom"` + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsAgent, err := client.Beta.Agents.Update( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentUpdateParams{ + Version: 1, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsAgent.ID) +} +``` + +## Archive + +`client.Beta.Agents.Archive(ctx, agentID, body) (*BetaManagedAgentsAgent, error)` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `agentID string` + +- `body BetaAgentArchiveParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsAgent, err := client.Beta.Agents.Archive( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentArchiveParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsAgent.ID) +} +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `type BetaManagedAgentsAgentToolConfig struct{…}` + + Configuration for a specific agent tool. + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Agent Tool Config Params + +- `type BetaManagedAgentsAgentToolConfigParamsResp struct{…}` + + Configuration override for a specific tool within a toolset. + + - `Name BetaManagedAgentsAgentToolConfigParamsName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigParamsNameBash BetaManagedAgentsAgentToolConfigParamsName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameEdit BetaManagedAgentsAgentToolConfigParamsName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameRead BetaManagedAgentsAgentToolConfigParamsName = "read"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWrite BetaManagedAgentsAgentToolConfigParamsName = "write"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGlob BetaManagedAgentsAgentToolConfigParamsName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGrep BetaManagedAgentsAgentToolConfigParamsName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebFetch BetaManagedAgentsAgentToolConfigParamsName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebSearch BetaManagedAgentsAgentToolConfigParamsName = "web_search"` + + - `Enabled bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Agent Toolset Default Config + +- `type BetaManagedAgentsAgentToolsetDefaultConfig struct{…}` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `type BetaManagedAgentsAgentToolsetDefaultConfigParamsResp struct{…}` + + Default configuration for all tools in a toolset. + + - `Enabled bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Agent Toolset20260401 + +- `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `type BetaManagedAgentsAgentToolset20260401ParamsResp struct{…}` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `Type BetaManagedAgentsAgentToolset20260401ParamsType` + + - `const BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401ParamsType = "agent_toolset_20260401"` + + - `Configs []BetaManagedAgentsAgentToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name BetaManagedAgentsAgentToolConfigParamsName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigParamsNameBash BetaManagedAgentsAgentToolConfigParamsName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameEdit BetaManagedAgentsAgentToolConfigParamsName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameRead BetaManagedAgentsAgentToolConfigParamsName = "read"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWrite BetaManagedAgentsAgentToolConfigParamsName = "write"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGlob BetaManagedAgentsAgentToolConfigParamsName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGrep BetaManagedAgentsAgentToolConfigParamsName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebFetch BetaManagedAgentsAgentToolConfigParamsName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebSearch BetaManagedAgentsAgentToolConfigParamsName = "web_search"` + + - `Enabled bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfigParamsResp` + + Default configuration for all tools in a toolset. + + - `Enabled bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Always Allow Policy + +- `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + +### Beta Managed Agents Always Ask Policy + +- `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Anthropic Skill + +- `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + +### Beta Managed Agents Anthropic Skill Params + +- `type BetaManagedAgentsAnthropicSkillParamsResp struct{…}` + + An Anthropic-managed skill. + + - `SkillID string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `Type BetaManagedAgentsAnthropicSkillParamsType` + + - `const BetaManagedAgentsAnthropicSkillParamsTypeAnthropic BetaManagedAgentsAnthropicSkillParamsType = "anthropic"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + +### Beta Managed Agents Custom Skill Params + +- `type BetaManagedAgentsCustomSkillParamsResp struct{…}` + + A user-created custom skill. + + - `SkillID string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `Type BetaManagedAgentsCustomSkillParamsType` + + - `const BetaManagedAgentsCustomSkillParamsTypeCustom BetaManagedAgentsCustomSkillParamsType = "custom"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + +### Beta Managed Agents Custom Tool Input Schema + +- `type BetaManagedAgentsCustomToolInputSchema struct{…}` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + +### Beta Managed Agents Custom Tool Params + +- `type BetaManagedAgentsCustomToolParamsResp struct{…}` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `Description string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `Type BetaManagedAgentsCustomToolParamsType` + + - `const BetaManagedAgentsCustomToolParamsTypeCustom BetaManagedAgentsCustomToolParamsType = "custom"` + +### Beta Managed Agents MCP Server URL Definition + +- `type BetaManagedAgentsMCPServerURLDefinition struct{…}` + + URL-based MCP server connection as returned in API responses. + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + +### Beta Managed Agents MCP Tool Config + +- `type BetaManagedAgentsMCPToolConfig struct{…}` + + Resolved configuration for a specific MCP tool. + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents MCP Tool Config Params + +- `type BetaManagedAgentsMCPToolConfigParamsResp struct{…}` + + Configuration override for a specific MCP tool. + + - `Name string` + + Name of the MCP tool to configure. 1-128 characters. + + - `Enabled bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents MCP Toolset + +- `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + +### Beta Managed Agents MCP Toolset Default Config + +- `type BetaManagedAgentsMCPToolsetDefaultConfig struct{…}` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `type BetaManagedAgentsMCPToolsetDefaultConfigParamsResp struct{…}` + + Default configuration for all tools from an MCP server. + + - `Enabled bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents MCP Toolset Params + +- `type BetaManagedAgentsMCPToolsetParamsResp struct{…}` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `MCPServerName string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `Type BetaManagedAgentsMCPToolsetParamsType` + + - `const BetaManagedAgentsMCPToolsetParamsTypeMCPToolset BetaManagedAgentsMCPToolsetParamsType = "mcp_toolset"` + + - `Configs []BetaManagedAgentsMCPToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name string` + + Name of the MCP tool to configure. 1-128 characters. + + - `Enabled bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfigParamsResp` + + Default configuration for all tools from an MCP server. + + - `Enabled bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Model + +- `type BetaManagedAgentsModel interface{…}` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + +### Beta Managed Agents Model Config + +- `type BetaManagedAgentsModelConfig struct{…}` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + +### Beta Managed Agents Model Config Params + +- `type BetaManagedAgentsModelConfigParamsResp struct{…}` + + An object that defines additional configuration control over model use + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigParamsSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigParamsSpeedStandard BetaManagedAgentsModelConfigParamsSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigParamsSpeedFast BetaManagedAgentsModelConfigParamsSpeed = "fast"` + +### Beta Managed Agents Skill Params + +- `type BetaManagedAgentsSkillParamsUnionResp interface{…}` + + Skill to load in the session container. + + - `type BetaManagedAgentsAnthropicSkillParamsResp struct{…}` + + An Anthropic-managed skill. + + - `SkillID string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `Type BetaManagedAgentsAnthropicSkillParamsType` + + - `const BetaManagedAgentsAnthropicSkillParamsTypeAnthropic BetaManagedAgentsAnthropicSkillParamsType = "anthropic"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + + - `type BetaManagedAgentsCustomSkillParamsResp struct{…}` + + A user-created custom skill. + + - `SkillID string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `Type BetaManagedAgentsCustomSkillParamsType` + + - `const BetaManagedAgentsCustomSkillParamsTypeCustom BetaManagedAgentsCustomSkillParamsType = "custom"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `type BetaManagedAgentsURLMCPServerParamsResp struct{…}` + + URL-based MCP server connection. + + - `Name string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `Type BetaManagedAgentsURLMCPServerParamsType` + + - `const BetaManagedAgentsURLMCPServerParamsTypeURL BetaManagedAgentsURLMCPServerParamsType = "url"` + + - `URL string` + + Endpoint URL for the MCP server. + +# Versions + +## List + +`client.Beta.Agents.Versions.List(ctx, agentID, params) (*PageCursor[BetaManagedAgentsAgent], error)` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agentID string` + +- `params BetaAgentVersionListParams` + + - `Limit param.Field[int64]` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Agents.Versions.List( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentVersionListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +# Environments + +## Create + +`client.Beta.Environments.New(ctx, params) (*BetaEnvironment, error)` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `params BetaEnvironmentNewParams` + + - `Name param.Field[string]` + + Body param: Human-readable name for the environment + + - `Config param.Field[BetaCloudConfigParamsResp]` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Description param.Field[string]` + + Body param: Optional description of the environment + + - `Metadata param.Field[map[string, string]]` + + Body param: User-provided metadata key-value pairs + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironment, err := client.Beta.Environments.New(context.TODO(), anthropic.BetaEnvironmentNewParams{ + Name: "python-data-analysis", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironment.ID) +} +``` + +## List + +`client.Beta.Environments.List(ctx, params) (*PageCursor[BetaEnvironment], error)` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `params BetaEnvironmentListParams` + + - `IncludeArchived param.Field[bool]` + + Query param: Include archived environments in the response + + - `Limit param.Field[int64]` + + Query param: Maximum number of environments to return + + - `Page param.Field[string]` + + Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Environments.List(context.TODO(), anthropic.BetaEnvironmentListParams{ + + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Environments.Get(ctx, environmentID, query) (*BetaEnvironment, error)` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `environmentID string` + +- `query BetaEnvironmentGetParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironment, err := client.Beta.Environments.Get( + context.TODO(), + "env_011CZkZ9X2dpNyB7HsEFoRfW", + anthropic.BetaEnvironmentGetParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironment.ID) +} +``` + +## Update + +`client.Beta.Environments.Update(ctx, environmentID, params) (*BetaEnvironment, error)` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `environmentID string` + +- `params BetaEnvironmentUpdateParams` + + - `Config param.Field[BetaCloudConfigParamsResp]` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Description param.Field[string]` + + Body param: Updated description of the environment + + - `Metadata param.Field[map[string, string]]` + + Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + + - `Name param.Field[string]` + + Body param: Updated name for the environment + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironment, err := client.Beta.Environments.Update( + context.TODO(), + "env_011CZkZ9X2dpNyB7HsEFoRfW", + anthropic.BetaEnvironmentUpdateParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironment.ID) +} +``` + +## Delete + +`client.Beta.Environments.Delete(ctx, environmentID, body) (*BetaEnvironmentDeleteResponse, error)` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `environmentID string` + +- `body BetaEnvironmentDeleteParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironmentDeleteResponse struct{…}` + + Response after deleting an environment. + + - `ID string` + + Environment identifier + + - `Type EnvironmentDeleted` + + The type of response + + - `const EnvironmentDeletedEnvironmentDeleted EnvironmentDeleted = "environment_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironmentDeleteResponse, err := client.Beta.Environments.Delete( + context.TODO(), + "env_011CZkZ9X2dpNyB7HsEFoRfW", + anthropic.BetaEnvironmentDeleteParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironmentDeleteResponse.ID) +} +``` + +## Archive + +`client.Beta.Environments.Archive(ctx, environmentID, body) (*BetaEnvironment, error)` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `environmentID string` + +- `body BetaEnvironmentArchiveParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironment, err := client.Beta.Environments.Archive( + context.TODO(), + "env_011CZkZ9X2dpNyB7HsEFoRfW", + anthropic.BetaEnvironmentArchiveParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironment.ID) +} +``` + +## Domain Types + +### Beta Cloud Config + +- `type BetaCloudConfig struct{…}` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + +### Beta Cloud Config Params + +- `type BetaCloudConfigParamsResp struct{…}` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `Networking BetaCloudConfigParamsNetworkingUnionResp` + + Network configuration policy. Omit on update to preserve the existing value. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetworkParamsResp struct{…}` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Packages BetaPackagesParamsResp` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesParamsType` + + Package configuration type + + - `const BetaPackagesParamsTypePackages BetaPackagesParamsType = "packages"` + +### Beta Environment + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `type BetaEnvironmentDeleteResponse struct{…}` + + Response after deleting an environment. + + - `ID string` + + Environment identifier + + - `Type EnvironmentDeleted` + + The type of response + + - `const EnvironmentDeletedEnvironmentDeleted EnvironmentDeleted = "environment_deleted"` + +### Beta Limited Network + +- `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + +### Beta Limited Network Params + +- `type BetaLimitedNetworkParamsResp struct{…}` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + +### Beta Packages + +- `type BetaPackages struct{…}` + + Packages (and their versions) available in this environment. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + +### Beta Packages Params + +- `type BetaPackagesParamsResp struct{…}` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesParamsType` + + Package configuration type + + - `const BetaPackagesParamsTypePackages BetaPackagesParamsType = "packages"` + +### Beta Unrestricted Network + +- `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + +# Sessions + +## Create + +`client.Beta.Sessions.New(ctx, params) (*BetaManagedAgentsSession, error)` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `params BetaSessionNewParams` + + - `Agent param.Field[BetaSessionNewParamsAgentUnion]` + + Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `string` + + - `type BetaManagedAgentsAgentParamsResp struct{…}` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `ID string` + + The `agent` ID. + + - `Type BetaManagedAgentsAgentParamsType` + + - `const BetaManagedAgentsAgentParamsTypeAgent BetaManagedAgentsAgentParamsType = "agent"` + + - `Version int64` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + + - `EnvironmentID param.Field[string]` + + Body param: ID of the `environment` defining the container configuration for this session. + + - `Metadata param.Field[map[string, string]]` + + Body param: Arbitrary key-value metadata attached to the session. + + - `Resources param.Field[[]BetaSessionNewParamsResourceUnion]` + + Body param: Resources (e.g. repositories, files) to mount into the session's container. + + - `type BetaManagedAgentsGitHubRepositoryResourceParamsResp struct{…}` + + Mount a GitHub repository into the session's container. + + - `AuthorizationToken string` + + GitHub authorization token used to clone the repository. + + - `Type BetaManagedAgentsGitHubRepositoryResourceParamsType` + + - `const BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceParamsType = "github_repository"` + + - `URL string` + + Github URL of the repository + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceParamsCheckoutUnionResp` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `MountPath string` + + Mount path in the container. Defaults to `/workspace/`. + + - `type BetaManagedAgentsFileResourceParamsResp struct{…}` + + Mount a file uploaded via the Files API into the session. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileResourceParamsType` + + - `const BetaManagedAgentsFileResourceParamsTypeFile BetaManagedAgentsFileResourceParamsType = "file"` + + - `MountPath string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `Title param.Field[string]` + + Body param: Human-readable session title. + + - `VaultIDs param.Field[[]string]` + + Body param: Vault IDs for stored credentials the agent can use during the session. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSession, err := client.Beta.Sessions.New(context.TODO(), anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{ + OfString: anthropic.String("agent_011CZkYpogX7uDKUyvBTophP"), + }, + EnvironmentID: "env_011CZkZ9X2dpNyB7HsEFoRfW", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSession.ID) +} +``` + +## List + +`client.Beta.Sessions.List(ctx, params) (*PageCursor[BetaManagedAgentsSession], error)` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `params BetaSessionListParams` + + - `AgentID param.Field[string]` + + Query param: Filter sessions created with this agent ID. + + - `AgentVersion param.Field[int64]` + + Query param: Filter by agent version. Only applies when agent_id is also set. + + - `CreatedAtGt param.Field[Time]` + + Query param: Return sessions created after this time (exclusive). + + - `CreatedAtGte param.Field[Time]` + + Query param: Return sessions created at or after this time (inclusive). + + - `CreatedAtLt param.Field[Time]` + + Query param: Return sessions created before this time (exclusive). + + - `CreatedAtLte param.Field[Time]` + + Query param: Return sessions created at or before this time (inclusive). + + - `IncludeArchived param.Field[bool]` + + Query param: When true, includes archived sessions. Default: false (exclude archived). + + - `Limit param.Field[int64]` + + Query param: Maximum number of results to return. + + - `Order param.Field[BetaSessionListParamsOrder]` + + Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `const BetaSessionListParamsOrderAsc BetaSessionListParamsOrder = "asc"` + + - `const BetaSessionListParamsOrderDesc BetaSessionListParamsOrder = "desc"` + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Sessions.List(context.TODO(), anthropic.BetaSessionListParams{ + + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Sessions.Get(ctx, sessionID, query) (*BetaManagedAgentsSession, error)` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `sessionID string` + +- `query BetaSessionGetParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSession, err := client.Beta.Sessions.Get( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionGetParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSession.ID) +} +``` + +## Update + +`client.Beta.Sessions.Update(ctx, sessionID, params) (*BetaManagedAgentsSession, error)` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `sessionID string` + +- `params BetaSessionUpdateParams` + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + + - `Title param.Field[string]` + + Body param: Human-readable session title. + + - `VaultIDs param.Field[[]string]` + + Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSession, err := client.Beta.Sessions.Update( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionUpdateParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSession.ID) +} +``` + +## Delete + +`client.Beta.Sessions.Delete(ctx, sessionID, body) (*BetaManagedAgentsDeletedSession, error)` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `sessionID string` + +- `body BetaSessionDeleteParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeletedSession struct{…}` + + Confirmation that a `session` has been permanently deleted. + + - `ID string` + + - `Type BetaManagedAgentsDeletedSessionType` + + - `const BetaManagedAgentsDeletedSessionTypeSessionDeleted BetaManagedAgentsDeletedSessionType = "session_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeletedSession, err := client.Beta.Sessions.Delete( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionDeleteParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeletedSession.ID) +} +``` + +## Archive + +`client.Beta.Sessions.Archive(ctx, sessionID, body) (*BetaManagedAgentsSession, error)` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `sessionID string` + +- `body BetaSessionArchiveParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSession, err := client.Beta.Sessions.Archive( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionArchiveParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSession.ID) +} +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `type BetaManagedAgentsAgentParamsResp struct{…}` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `ID string` + + The `agent` ID. + + - `Type BetaManagedAgentsAgentParamsType` + + - `const BetaManagedAgentsAgentParamsTypeAgent BetaManagedAgentsAgentParamsType = "agent"` + + - `Version int64` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + +### Beta Managed Agents Cache Creation Usage + +- `type BetaManagedAgentsCacheCreationUsage struct{…}` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + +### Beta Managed Agents Deleted Session + +- `type BetaManagedAgentsDeletedSession struct{…}` + + Confirmation that a `session` has been permanently deleted. + + - `ID string` + + - `Type BetaManagedAgentsDeletedSessionType` + + - `const BetaManagedAgentsDeletedSessionTypeSessionDeleted BetaManagedAgentsDeletedSessionType = "session_deleted"` + +### Beta Managed Agents File Resource Params + +- `type BetaManagedAgentsFileResourceParamsResp struct{…}` + + Mount a file uploaded via the Files API into the session. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileResourceParamsType` + + - `const BetaManagedAgentsFileResourceParamsTypeFile BetaManagedAgentsFileResourceParamsType = "file"` + + - `MountPath string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `type BetaManagedAgentsGitHubRepositoryResourceParamsResp struct{…}` + + Mount a GitHub repository into the session's container. + + - `AuthorizationToken string` + + GitHub authorization token used to clone the repository. + + - `Type BetaManagedAgentsGitHubRepositoryResourceParamsType` + + - `const BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceParamsType = "github_repository"` + + - `URL string` + + Github URL of the repository + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceParamsCheckoutUnionResp` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `MountPath string` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `type BetaManagedAgentsSessionAgent struct{…}` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + +### Beta Managed Agents Session Stats + +- `type BetaManagedAgentsSessionStats struct{…}` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `type BetaManagedAgentsSessionUsage struct{…}` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + +# Events + +## List + +`client.Beta.Sessions.Events.List(ctx, sessionID, params) (*PageCursor[BetaManagedAgentsSessionEventUnion], error)` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `sessionID string` + +- `params BetaSessionEventListParams` + + - `Limit param.Field[int64]` + + Query param: Query parameter for limit + + - `Order param.Field[BetaSessionEventListParamsOrder]` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `const BetaSessionEventListParamsOrderAsc BetaSessionEventListParamsOrder = "asc"` + + - `const BetaSessionEventListParamsOrderDesc BetaSessionEventListParamsOrder = "desc"` + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSessionEventUnion interface{…}` + + Union type for all event types in a session. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Sessions.Events.List( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionEventListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Send + +`client.Beta.Sessions.Events.Send(ctx, sessionID, params) (*BetaManagedAgentsSendSessionEvents, error)` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `sessionID string` + +- `params BetaSessionEventSendParams` + + - `Events param.Field[[]BetaManagedAgentsEventParamsUnionResp]` + + Body param: Events to send to the `session`. + + - `type BetaManagedAgentsUserMessageEventParamsResp struct{…}` + + Parameters for sending a user message to the session. + + - `Content []BetaManagedAgentsUserMessageEventParamsContentUnionResp` + + Array of content blocks for the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventParamsType` + + - `const BetaManagedAgentsUserMessageEventParamsTypeUserMessage BetaManagedAgentsUserMessageEventParamsType = "user.message"` + + - `type BetaManagedAgentsUserInterruptEventParamsResp struct{…}` + + Parameters for sending an interrupt to pause the agent. + + - `Type BetaManagedAgentsUserInterruptEventParamsType` + + - `const BetaManagedAgentsUserInterruptEventParamsTypeUserInterrupt BetaManagedAgentsUserInterruptEventParamsType = "user.interrupt"` + + - `type BetaManagedAgentsUserToolConfirmationEventParamsResp struct{…}` + + Parameters for confirming or denying a tool execution request. + + - `Result BetaManagedAgentsUserToolConfirmationEventParamsResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultAllow BetaManagedAgentsUserToolConfirmationEventParamsResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultDeny BetaManagedAgentsUserToolConfirmationEventParamsResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventParamsType` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventParamsType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `type BetaManagedAgentsUserCustomToolResultEventParamsResp struct{…}` + + Parameters for providing the result of a custom tool execution. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventParamsType` + + - `const BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventParamsType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventParamsContentUnionResp` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSendSessionEvents struct{…}` + + Events that were successfully sent to the session. + + - `Data []BetaManagedAgentsSendSessionEventsDataUnion` + + Sent events + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSendSessionEvents, err := client.Beta.Sessions.Events.Send( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionEventSendParams{ + Events: []anthropic.BetaManagedAgentsEventParamsUnion{anthropic.BetaManagedAgentsEventParamsUnion{ + OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{ + Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{ + OfText: &anthropic.BetaManagedAgentsTextBlockParam{ + Text: "Where is my order #1234?", + Type: anthropic.BetaManagedAgentsTextBlockTypeText, + }, + }}, + Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage, + }, + }}, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSendSessionEvents.Data) +} +``` + +## Stream + +`client.Beta.Sessions.Events.Stream(ctx, sessionID, query) (*BetaManagedAgentsStreamSessionEventsUnion, error)` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `sessionID string` + +- `query BetaSessionEventStreamParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsStreamSessionEventsUnion interface{…}` + + Server-sent event in the session stream. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + stream := client.Beta.Sessions.Events.StreamEvents( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionEventStreamParams{ + + }, + ) + for stream.Next() { + fmt.Printf("%+v\n", stream.Current()) + } + err := stream.Err() + if err != nil { + panic(err.Error()) + } +} +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + +### Beta Managed Agents Agent Message Event + +- `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + +### Beta Managed Agents Base64 Document Source + +- `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + +### Beta Managed Agents Base64 Image Source + +- `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + +### Beta Managed Agents Billing Error + +- `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + +### Beta Managed Agents Document Block + +- `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + +### Beta Managed Agents Event Params + +- `type BetaManagedAgentsEventParamsUnionResp interface{…}` + + Union type for event parameters that can be sent to a session. + + - `type BetaManagedAgentsUserMessageEventParamsResp struct{…}` + + Parameters for sending a user message to the session. + + - `Content []BetaManagedAgentsUserMessageEventParamsContentUnionResp` + + Array of content blocks for the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventParamsType` + + - `const BetaManagedAgentsUserMessageEventParamsTypeUserMessage BetaManagedAgentsUserMessageEventParamsType = "user.message"` + + - `type BetaManagedAgentsUserInterruptEventParamsResp struct{…}` + + Parameters for sending an interrupt to pause the agent. + + - `Type BetaManagedAgentsUserInterruptEventParamsType` + + - `const BetaManagedAgentsUserInterruptEventParamsTypeUserInterrupt BetaManagedAgentsUserInterruptEventParamsType = "user.interrupt"` + + - `type BetaManagedAgentsUserToolConfirmationEventParamsResp struct{…}` + + Parameters for confirming or denying a tool execution request. + + - `Result BetaManagedAgentsUserToolConfirmationEventParamsResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultAllow BetaManagedAgentsUserToolConfirmationEventParamsResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultDeny BetaManagedAgentsUserToolConfirmationEventParamsResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventParamsType` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventParamsType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `type BetaManagedAgentsUserCustomToolResultEventParamsResp struct{…}` + + Parameters for providing the result of a custom tool execution. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventParamsType` + + - `const BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventParamsType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventParamsContentUnionResp` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + +### Beta Managed Agents File Image Source + +- `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + +### Beta Managed Agents Image Block + +- `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + +### Beta Managed Agents Retry Status Exhausted + +- `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + +### Beta Managed Agents Send Session Events + +- `type BetaManagedAgentsSendSessionEvents struct{…}` + + Events that were successfully sent to the session. + + - `Data []BetaManagedAgentsSendSessionEventsDataUnion` + + Sent events + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Beta Managed Agents Session End Turn + +- `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + +### Beta Managed Agents Session Error Event + +- `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + +### Beta Managed Agents Session Event + +- `type BetaManagedAgentsSessionEventUnion interface{…}` + + Union type for all event types in a session. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `type BetaManagedAgentsSpanModelUsage struct{…}` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + +### Beta Managed Agents Stream Session Events + +- `type BetaManagedAgentsStreamSessionEventsUnion interface{…}` + + Server-sent event in the session stream. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Beta Managed Agents Text Block + +- `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + +### Beta Managed Agents Unknown Error + +- `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + +### Beta Managed Agents URL Document Source + +- `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `type BetaManagedAgentsUserCustomToolResultEventParamsResp struct{…}` + + Parameters for providing the result of a custom tool execution. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventParamsType` + + - `const BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventParamsType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventParamsContentUnionResp` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `type BetaManagedAgentsUserInterruptEventParamsResp struct{…}` + + Parameters for sending an interrupt to pause the agent. + + - `Type BetaManagedAgentsUserInterruptEventParamsType` + + - `const BetaManagedAgentsUserInterruptEventParamsTypeUserInterrupt BetaManagedAgentsUserInterruptEventParamsType = "user.interrupt"` + +### Beta Managed Agents User Message Event + +- `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `type BetaManagedAgentsUserMessageEventParamsResp struct{…}` + + Parameters for sending a user message to the session. + + - `Content []BetaManagedAgentsUserMessageEventParamsContentUnionResp` + + Array of content blocks for the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventParamsType` + + - `const BetaManagedAgentsUserMessageEventParamsTypeUserMessage BetaManagedAgentsUserMessageEventParamsType = "user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `type BetaManagedAgentsUserToolConfirmationEventParamsResp struct{…}` + + Parameters for confirming or denying a tool execution request. + + - `Result BetaManagedAgentsUserToolConfirmationEventParamsResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultAllow BetaManagedAgentsUserToolConfirmationEventParamsResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultDeny BetaManagedAgentsUserToolConfirmationEventParamsResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventParamsType` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventParamsType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`client.Beta.Sessions.Resources.Add(ctx, sessionID, params) (*BetaManagedAgentsFileResource, error)` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `sessionID string` + +- `params BetaSessionResourceAddParams` + + - `BetaManagedAgentsFileResourceParams param.Field[BetaManagedAgentsFileResourceParamsResp]` + + Body param: Mount a file uploaded via the Files API into the session. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsFileResource, err := client.Beta.Sessions.Resources.Add( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionResourceAddParams{ + BetaManagedAgentsFileResourceParams: anthropic.BetaManagedAgentsFileResourceParams{ + FileID: "file_011CNha8iCJcU1wXNR6q4V8w", + Type: anthropic.BetaManagedAgentsFileResourceParamsTypeFile, + }, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsFileResource.ID) +} +``` + +## List + +`client.Beta.Sessions.Resources.List(ctx, sessionID, params) (*PageCursor[BetaManagedAgentsSessionResourceUnion], error)` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `sessionID string` + +- `params BetaSessionResourceListParams` + + - `Limit param.Field[int64]` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `Page param.Field[string]` + + Query param: Opaque cursor from a previous response's next_page field. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSessionResourceUnion interface{…}` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Sessions.Resources.List( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionResourceListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Sessions.Resources.Get(ctx, resourceID, params) (*BetaSessionResourceGetResponseUnion, error)` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `resourceID string` + +- `params BetaSessionResourceGetParams` + + - `SessionID param.Field[string]` + + Path param: Path parameter session_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaSessionResourceGetResponseUnion interface{…}` + + The requested session resource. + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + resource, err := client.Beta.Sessions.Resources.Get( + context.TODO(), + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + anthropic.BetaSessionResourceGetParams{ + SessionID: "sesn_011CZkZAtmR3yMPDzynEDxu7", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", resource) +} +``` + +## Update + +`client.Beta.Sessions.Resources.Update(ctx, resourceID, params) (*BetaSessionResourceUpdateResponseUnion, error)` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `resourceID string` + +- `params BetaSessionResourceUpdateParams` + + - `SessionID param.Field[string]` + + Path param: Path parameter session_id + + - `AuthorizationToken param.Field[string]` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaSessionResourceUpdateResponseUnion interface{…}` + + The updated session resource. + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + resource, err := client.Beta.Sessions.Resources.Update( + context.TODO(), + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + anthropic.BetaSessionResourceUpdateParams{ + SessionID: "sesn_011CZkZAtmR3yMPDzynEDxu7", + AuthorizationToken: "ghp_exampletoken", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", resource) +} +``` + +## Delete + +`client.Beta.Sessions.Resources.Delete(ctx, resourceID, params) (*BetaManagedAgentsDeleteSessionResource, error)` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `resourceID string` + +- `params BetaSessionResourceDeleteParams` + + - `SessionID param.Field[string]` + + Path param: Path parameter session_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeleteSessionResource struct{…}` + + Confirmation of resource deletion. + + - `ID string` + + - `Type BetaManagedAgentsDeleteSessionResourceType` + + - `const BetaManagedAgentsDeleteSessionResourceTypeSessionResourceDeleted BetaManagedAgentsDeleteSessionResourceType = "session_resource_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeleteSessionResource, err := client.Beta.Sessions.Resources.Delete( + context.TODO(), + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + anthropic.BetaSessionResourceDeleteParams{ + SessionID: "sesn_011CZkZAtmR3yMPDzynEDxu7", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeleteSessionResource.ID) +} +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `type BetaManagedAgentsDeleteSessionResource struct{…}` + + Confirmation of resource deletion. + + - `ID string` + + - `Type BetaManagedAgentsDeleteSessionResourceType` + + - `const BetaManagedAgentsDeleteSessionResourceTypeSessionResourceDeleted BetaManagedAgentsDeleteSessionResourceType = "session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + +### Beta Managed Agents Session Resource + +- `type BetaManagedAgentsSessionResourceUnion interface{…}` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +# Vaults + +## Create + +`client.Beta.Vaults.New(ctx, params) (*BetaManagedAgentsVault, error)` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `params BetaVaultNewParams` + + - `DisplayName param.Field[string]` + + Body param: Human-readable name for the vault. 1-255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Arbitrary key-value metadata to attach to the vault. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsVault, err := client.Beta.Vaults.New(context.TODO(), anthropic.BetaVaultNewParams{ + DisplayName: "Example vault", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsVault.ID) +} +``` + +## List + +`client.Beta.Vaults.List(ctx, params) (*PageCursor[BetaManagedAgentsVault], error)` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `params BetaVaultListParams` + + - `IncludeArchived param.Field[bool]` + + Query param: Whether to include archived vaults in the results. + + - `Limit param.Field[int64]` + + Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination token from a previous `list_vaults` response. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Vaults.List(context.TODO(), anthropic.BetaVaultListParams{ + + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Vaults.Get(ctx, vaultID, query) (*BetaManagedAgentsVault, error)` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `vaultID string` + +- `query BetaVaultGetParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsVault, err := client.Beta.Vaults.Get( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultGetParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsVault.ID) +} +``` + +## Update + +`client.Beta.Vaults.Update(ctx, vaultID, params) (*BetaManagedAgentsVault, error)` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `vaultID string` + +- `params BetaVaultUpdateParams` + + - `DisplayName param.Field[string]` + + Body param: Updated human-readable name for the vault. 1-255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsVault, err := client.Beta.Vaults.Update( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultUpdateParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsVault.ID) +} +``` + +## Delete + +`client.Beta.Vaults.Delete(ctx, vaultID, body) (*BetaManagedAgentsDeletedVault, error)` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `vaultID string` + +- `body BetaVaultDeleteParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeletedVault struct{…}` + + Confirmation of a deleted vault. + + - `ID string` + + Unique identifier of the deleted vault. + + - `Type BetaManagedAgentsDeletedVaultType` + + - `const BetaManagedAgentsDeletedVaultTypeVaultDeleted BetaManagedAgentsDeletedVaultType = "vault_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeletedVault, err := client.Beta.Vaults.Delete( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultDeleteParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeletedVault.ID) +} +``` + +## Archive + +`client.Beta.Vaults.Archive(ctx, vaultID, body) (*BetaManagedAgentsVault, error)` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `vaultID string` + +- `body BetaVaultArchiveParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsVault, err := client.Beta.Vaults.Archive( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultArchiveParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsVault.ID) +} +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `type BetaManagedAgentsDeletedVault struct{…}` + + Confirmation of a deleted vault. + + - `ID string` + + Unique identifier of the deleted vault. + + - `Type BetaManagedAgentsDeletedVaultType` + + - `const BetaManagedAgentsDeletedVaultTypeVaultDeleted BetaManagedAgentsDeletedVaultType = "vault_deleted"` + +### Beta Managed Agents Vault + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`client.Beta.Vaults.Credentials.New(ctx, vaultID, params) (*BetaManagedAgentsCredential, error)` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vaultID string` + +- `params BetaVaultCredentialNewParams` + + - `Auth param.Field[BetaVaultCredentialNewParamsAuthUnion]` + + Body param: Authentication details for creating a credential. + + - `type BetaManagedAgentsMCPOAuthCreateParamsResp struct{…}` + + Parameters for creating an MCP OAuth credential. + + - `AccessToken string` + + OAuth access token. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthCreateParamsType` + + - `const BetaManagedAgentsMCPOAuthCreateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthCreateParamsType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshParamsResp` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `ClientID string` + + OAuth client ID. + + - `RefreshToken string` + + OAuth refresh token. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnionResp` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerCreateParamsResp struct{…}` + + Parameters for creating a static bearer token credential. + + - `Token string` + + Static bearer token value. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerCreateParamsType` + + - `const BetaManagedAgentsStaticBearerCreateParamsTypeStaticBearer BetaManagedAgentsStaticBearerCreateParamsType = "static_bearer"` + + - `DisplayName param.Field[string]` + + Body param: Human-readable name for the credential. Up to 255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Arbitrary key-value metadata to attach to the credential. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.New( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultCredentialNewParams{ + Auth: anthropic.BetaVaultCredentialNewParamsAuthUnion{ + OfStaticBearer: &anthropic.BetaManagedAgentsStaticBearerCreateParams{ + Token: "bearer_exampletoken", + MCPServerURL: "https://example-server.modelcontextprotocol.io/sse", + Type: anthropic.BetaManagedAgentsStaticBearerCreateParamsTypeStaticBearer, + }, + }, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` + +## List + +`client.Beta.Vaults.Credentials.List(ctx, vaultID, params) (*PageCursor[BetaManagedAgentsCredential], error)` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vaultID string` + +- `params BetaVaultCredentialListParams` + + - `IncludeArchived param.Field[bool]` + + Query param: Whether to include archived credentials in the results. + + - `Limit param.Field[int64]` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination token from a previous `list_credentials` response. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Vaults.Credentials.List( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultCredentialListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Vaults.Credentials.Get(ctx, credentialID, params) (*BetaManagedAgentsCredential, error)` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialGetParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.Get( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialGetParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` + +## Update + +`client.Beta.Vaults.Credentials.Update(ctx, credentialID, params) (*BetaManagedAgentsCredential, error)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialUpdateParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Auth param.Field[BetaVaultCredentialUpdateParamsAuthUnion]` + + Body param: Updated authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthUpdateParamsResp struct{…}` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsMCPOAuthUpdateParamsType` + + - `const BetaManagedAgentsMCPOAuthUpdateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthUpdateParamsType = "mcp_oauth"` + + - `AccessToken string` + + Updated OAuth access token. + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshUpdateParamsResp` + + Parameters for updating OAuth refresh token configuration. + + - `RefreshToken string` + + Updated OAuth refresh token. + + - `Scope string` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshUpdateParamsTokenEndpointAuthUnionResp` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` + + Updated POST body authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsStaticBearerUpdateParamsResp struct{…}` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsStaticBearerUpdateParamsType` + + - `const BetaManagedAgentsStaticBearerUpdateParamsTypeStaticBearer BetaManagedAgentsStaticBearerUpdateParamsType = "static_bearer"` + + - `Token string` + + Updated static bearer token value. + + - `DisplayName param.Field[string]` + + Body param: Updated human-readable name for the credential. 1-255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.Update( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialUpdateParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` + +## Delete + +`client.Beta.Vaults.Credentials.Delete(ctx, credentialID, params) (*BetaManagedAgentsDeletedCredential, error)` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialDeleteParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeletedCredential struct{…}` + + Confirmation of a deleted credential. + + - `ID string` + + Unique identifier of the deleted credential. + + - `Type BetaManagedAgentsDeletedCredentialType` + + - `const BetaManagedAgentsDeletedCredentialTypeVaultCredentialDeleted BetaManagedAgentsDeletedCredentialType = "vault_credential_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeletedCredential, err := client.Beta.Vaults.Credentials.Delete( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialDeleteParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeletedCredential.ID) +} +``` + +## Archive + +`client.Beta.Vaults.Credentials.Archive(ctx, credentialID, params) (*BetaManagedAgentsCredential, error)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialArchiveParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.Archive( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialArchiveParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `type BetaManagedAgentsDeletedCredential struct{…}` + + Confirmation of a deleted credential. + + - `ID string` + + Unique identifier of the deleted credential. + + - `Type BetaManagedAgentsDeletedCredentialType` + + - `const BetaManagedAgentsDeletedCredentialTypeVaultCredentialDeleted BetaManagedAgentsDeletedCredentialType = "vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `type BetaManagedAgentsMCPOAuthCreateParamsResp struct{…}` + + Parameters for creating an MCP OAuth credential. + + - `AccessToken string` + + OAuth access token. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthCreateParamsType` + + - `const BetaManagedAgentsMCPOAuthCreateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthCreateParamsType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshParamsResp` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `ClientID string` + + OAuth client ID. + + - `RefreshToken string` + + OAuth refresh token. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnionResp` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `type BetaManagedAgentsMCPOAuthRefreshParamsResp struct{…}` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `ClientID string` + + OAuth client ID. + + - `RefreshToken string` + + OAuth refresh token. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnionResp` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `type BetaManagedAgentsMCPOAuthRefreshResponse struct{…}` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `type BetaManagedAgentsMCPOAuthRefreshUpdateParamsResp struct{…}` + + Parameters for updating OAuth refresh token configuration. + + - `RefreshToken string` + + Updated OAuth refresh token. + + - `Scope string` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshUpdateParamsTokenEndpointAuthUnionResp` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` + + Updated POST body authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` + + - `ClientSecret string` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `type BetaManagedAgentsMCPOAuthUpdateParamsResp struct{…}` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsMCPOAuthUpdateParamsType` + + - `const BetaManagedAgentsMCPOAuthUpdateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthUpdateParamsType = "mcp_oauth"` + + - `AccessToken string` + + Updated OAuth access token. + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshUpdateParamsResp` + + Parameters for updating OAuth refresh token configuration. + + - `RefreshToken string` + + Updated OAuth refresh token. + + - `Scope string` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshUpdateParamsTokenEndpointAuthUnionResp` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` + + Updated POST body authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` + + - `ClientSecret string` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `type BetaManagedAgentsStaticBearerCreateParamsResp struct{…}` + + Parameters for creating a static bearer token credential. + + - `Token string` + + Static bearer token value. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerCreateParamsType` + + - `const BetaManagedAgentsStaticBearerCreateParamsTypeStaticBearer BetaManagedAgentsStaticBearerCreateParamsType = "static_bearer"` + +### Beta Managed Agents Static Bearer Update Params - - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` +- `type BetaManagedAgentsStaticBearerUpdateParamsResp struct{…}` - - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. - - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + - `Type BetaManagedAgentsStaticBearerUpdateParamsType` - - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + - `const BetaManagedAgentsStaticBearerUpdateParamsTypeStaticBearer BetaManagedAgentsStaticBearerUpdateParamsType = "static_bearer"` - - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + - `Token string` - - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + Updated static bearer token value. - - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` +### Beta Managed Agents Token Endpoint Auth Basic Param - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` +- `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` -### Returns + Token endpoint uses HTTP Basic authentication with client credentials. -- `type DeletedFile struct{…}` + - `ClientSecret string` - - `ID string` + OAuth client secret. - ID of the deleted file. + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` - - `Type DeletedFileType` + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` - Deleted object type. +### Beta Managed Agents Token Endpoint Auth Basic Response - For file deletion, this is always `"file_deleted"`. +- `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` - - `const DeletedFileTypeFileDeleted DeletedFileType = "file_deleted"` + Token endpoint uses HTTP Basic authentication with client credentials. -### Example + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` -```go -package main + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` -import ( - "context" - "fmt" +### Beta Managed Agents Token Endpoint Auth Basic Update Param - "github.com/anthropics/anthropic-sdk-go" - "github.com/anthropics/anthropic-sdk-go/option" -) +- `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` -func main() { - client := anthropic.NewClient( - option.WithAPIKey("my-anthropic-api-key"), - ) - deletedFile, err := client.Beta.Files.Delete( - context.TODO(), - "file_id", - anthropic.BetaFileDeleteParams{ + Updated HTTP Basic authentication parameters for the token endpoint. - }, - ) - if err != nil { - panic(err.Error()) - } - fmt.Printf("%+v\n", deletedFile.ID) -} -``` + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` -## Domain Types + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` -### Deleted File + - `ClientSecret string` -- `type DeletedFile struct{…}` + Updated OAuth client secret. - - `ID string` +### Beta Managed Agents Token Endpoint Auth None Param - ID of the deleted file. +- `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` - - `Type DeletedFileType` + Token endpoint requires no client authentication. - Deleted object type. + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` - For file deletion, this is always `"file_deleted"`. + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` - - `const DeletedFileTypeFileDeleted DeletedFileType = "file_deleted"` +### Beta Managed Agents Token Endpoint Auth None Response -### File Metadata +- `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` -- `type FileMetadata struct{…}` + Token endpoint requires no client authentication. - - `ID string` + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` - Unique object identifier. + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` - The format and length of IDs may change over time. +### Beta Managed Agents Token Endpoint Auth Post Param - - `CreatedAt Time` +- `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` - RFC 3339 datetime string representing when the file was created. + Token endpoint uses POST body authentication with client credentials. - - `Filename string` + - `ClientSecret string` - Original filename of the uploaded file. + OAuth client secret. - - `MimeType string` + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` - MIME type of the file. + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` - - `SizeBytes int64` +### Beta Managed Agents Token Endpoint Auth Post Response - Size of the file in bytes. +- `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` - - `Type File` + Token endpoint uses POST body authentication with client credentials. - Object type. + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` - For files, this is always `"file"`. + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` - - `const FileFile File = "file"` +### Beta Managed Agents Token Endpoint Auth Post Update Param - - `Downloadable bool` +- `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` - Whether the file can be downloaded. + Updated POST body authentication parameters for the token endpoint. -# Skills + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` -## Create + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` -`client.Beta.Skills.New(ctx, params) (*BetaSkillNewResponse, error)` + - `ClientSecret string` -**post** `/v1/skills` + Updated OAuth client secret. -Create Skill +# Files -### Parameters +## Upload -- `params BetaSkillNewParams` +`client.Beta.Files.Upload(ctx, params) (*FileMetadata, error)` - - `DisplayTitle param.Field[string]` +**post** `/v1/files` - Body param: Display title for the skill. +Upload File - This is a human-readable label that is not included in the prompt sent to the model. +### Parameters - - `Files param.Field[[]Reader]` +- `params BetaFileUploadParams` - Body param: Files to upload for the skill. + - `File param.Field[Reader]` - All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. + Body param: The file to upload - `Betas param.Field[[]AnthropicBeta]` @@ -45613,52 +68138,57 @@ Create Skill - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaSkillNewResponse struct{…}` +- `type FileMetadata struct{…}` - `ID string` - Unique identifier for the skill. + Unique object identifier. The format and length of IDs may change over time. - - `CreatedAt string` + - `CreatedAt Time` - ISO 8601 timestamp of when the skill was created. + RFC 3339 datetime string representing when the file was created. - - `DisplayTitle string` + - `Filename string` - Display title for the skill. + Original filename of the uploaded file. - This is a human-readable label that is not included in the prompt sent to the model. + - `MimeType string` - - `LatestVersion string` + MIME type of the file. - The latest version identifier for the skill. + - `SizeBytes int64` - This represents the most recent version of the skill that has been created. + Size of the file in bytes. - - `Source string` + - `Type File` - Source of the skill. + Object type. - This may be one of the following values: + For files, this is always `"file"`. - * `"custom"`: the skill was created by a user - * `"anthropic"`: the skill was created by Anthropic + - `const FileFile File = "file"` - - `Type string` + - `Downloadable bool` - Object type. + Whether the file can be downloaded. - For Skills, this is always `"skill"`. + - `Scope BetaFileScope` - - `UpdatedAt string` + The scope of this file, indicating the context in which it was created (e.g., a session). - ISO 8601 timestamp of when the skill was last updated. + - `ID string` + + The ID of the scoping resource (e.g., the session ID). + + - `Type Session` + + The type of scope (e.g., `"session"`). + + - `const SessionSession Session = "session"` ### Example @@ -45666,8 +68196,10 @@ Create Skill package main import ( + "bytes" "context" "fmt" + "io" "github.com/anthropics/anthropic-sdk-go" "github.com/anthropics/anthropic-sdk-go/option" @@ -45677,48 +68209,45 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - skill, err := client.Beta.Skills.New(context.TODO(), anthropic.BetaSkillNewParams{ - + fileMetadata, err := client.Beta.Files.Upload(context.TODO(), anthropic.BetaFileUploadParams{ + File: io.Reader(bytes.NewBuffer([]byte("Example data"))), }) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", skill.ID) + fmt.Printf("%+v\n", fileMetadata.ID) } ``` ## List -`client.Beta.Skills.List(ctx, params) (*PageCursor[BetaSkillListResponse], error)` +`client.Beta.Files.List(ctx, params) (*Page[FileMetadata], error)` -**get** `/v1/skills` +**get** `/v1/files` -List Skills +List Files ### Parameters -- `params BetaSkillListParams` - - - `Limit param.Field[int64]` +- `params BetaFileListParams` - Query param: Number of results to return per page. + - `AfterID param.Field[string]` - Maximum value is 100. Defaults to 20. + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - - `Page param.Field[string]` + - `BeforeID param.Field[string]` - Query param: Pagination token for fetching a specific page of results. + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - Pass the value from a previous response's `next_page` field to get the next page of results. + - `Limit param.Field[int64]` - - `Source param.Field[string]` + Query param: Number of items to return per page. - Query param: Filter skills by source. + Defaults to `20`. Ranges from `1` to `1000`. - If provided, only skills from the specified source will be returned: + - `ScopeID param.Field[string]` - * `"custom"`: only return user-created skills - * `"anthropic"`: only return Anthropic-created skills + Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). - `Betas param.Field[[]AnthropicBeta]` @@ -45770,52 +68299,57 @@ List Skills - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaSkillListResponse struct{…}` +- `type FileMetadata struct{…}` - `ID string` - Unique identifier for the skill. + Unique object identifier. The format and length of IDs may change over time. - - `CreatedAt string` + - `CreatedAt Time` - ISO 8601 timestamp of when the skill was created. + RFC 3339 datetime string representing when the file was created. - - `DisplayTitle string` + - `Filename string` - Display title for the skill. + Original filename of the uploaded file. - This is a human-readable label that is not included in the prompt sent to the model. + - `MimeType string` - - `LatestVersion string` + MIME type of the file. - The latest version identifier for the skill. + - `SizeBytes int64` - This represents the most recent version of the skill that has been created. + Size of the file in bytes. - - `Source string` + - `Type File` - Source of the skill. + Object type. - This may be one of the following values: + For files, this is always `"file"`. - * `"custom"`: the skill was created by a user - * `"anthropic"`: the skill was created by Anthropic + - `const FileFile File = "file"` - - `Type string` + - `Downloadable bool` - Object type. + Whether the file can be downloaded. - For Skills, this is always `"skill"`. + - `Scope BetaFileScope` - - `UpdatedAt string` + The scope of this file, indicating the context in which it was created (e.g., a session). - ISO 8601 timestamp of when the skill was last updated. + - `ID string` + + The ID of the scoping resource (e.g., the session ID). + + - `Type Session` + + The type of scope (e.g., `"session"`). + + - `const SessionSession Session = "session"` ### Example @@ -45834,7 +68368,7 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - page, err := client.Beta.Skills.List(context.TODO(), anthropic.BetaSkillListParams{ + page, err := client.Beta.Files.List(context.TODO(), anthropic.BetaFileListParams{ }) if err != nil { @@ -45844,23 +68378,21 @@ func main() { } ``` -## Retrieve +## Download -`client.Beta.Skills.Get(ctx, skillID, query) (*BetaSkillGetResponse, error)` +`client.Beta.Files.Download(ctx, fileID, query) (*Response, error)` -**get** `/v1/skills/{skill_id}` +**get** `/v1/files/{file_id}/content` -Get Skill +Download File ### Parameters -- `skillID string` - - Unique identifier for the skill. +- `fileID string` - The format and length of IDs may change over time. + ID of the File. -- `query BetaSkillGetParams` +- `query BetaFileDownloadParams` - `Betas param.Field[[]AnthropicBeta]` @@ -45912,52 +68444,9 @@ Get Skill - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaSkillGetResponse struct{…}` - - - `ID string` - - Unique identifier for the skill. - - The format and length of IDs may change over time. - - - `CreatedAt string` - - ISO 8601 timestamp of when the skill was created. - - - `DisplayTitle string` - - Display title for the skill. - - This is a human-readable label that is not included in the prompt sent to the model. - - - `LatestVersion string` - - The latest version identifier for the skill. - - This represents the most recent version of the skill that has been created. - - - `Source string` - - Source of the skill. - - This may be one of the following values: - - * `"custom"`: the skill was created by a user - * `"anthropic"`: the skill was created by Anthropic - - - `Type string` - - Object type. - - For Skills, this is always `"skill"`. - - - `UpdatedAt string` - - ISO 8601 timestamp of when the skill was last updated. +- `type BetaFileDownloadResponse interface{…}` ### Example @@ -45976,37 +68465,35 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - skill, err := client.Beta.Skills.Get( + response, err := client.Beta.Files.Download( context.TODO(), - "skill_id", - anthropic.BetaSkillGetParams{ + "file_id", + anthropic.BetaFileDownloadParams{ }, ) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", skill.ID) + fmt.Printf("%+v\n", response) } ``` -## Delete +## Retrieve Metadata -`client.Beta.Skills.Delete(ctx, skillID, body) (*BetaSkillDeleteResponse, error)` +`client.Beta.Files.GetMetadata(ctx, fileID, query) (*FileMetadata, error)` -**delete** `/v1/skills/{skill_id}` +**get** `/v1/files/{file_id}` -Delete Skill +Get File Metadata ### Parameters -- `skillID string` - - Unique identifier for the skill. +- `fileID string` - The format and length of IDs may change over time. + ID of the File. -- `body BetaSkillDeleteParams` +- `query BetaFileGetMetadataParams` - `Betas param.Field[[]AnthropicBeta]` @@ -46058,23 +68545,57 @@ Delete Skill - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaSkillDeleteResponse struct{…}` +- `type FileMetadata struct{…}` - `ID string` - Unique identifier for the skill. + Unique object identifier. The format and length of IDs may change over time. - - `Type string` + - `CreatedAt Time` - Deleted object type. + RFC 3339 datetime string representing when the file was created. - For Skills, this is always `"skill_deleted"`. + - `Filename string` + + Original filename of the uploaded file. + + - `MimeType string` + + MIME type of the file. + + - `SizeBytes int64` + + Size of the file in bytes. + + - `Type File` + + Object type. + + For files, this is always `"file"`. + + - `const FileFile File = "file"` + + - `Downloadable bool` + + Whether the file can be downloaded. + + - `Scope BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `ID string` + + The ID of the scoping resource (e.g., the session ID). + + - `Type Session` + + The type of scope (e.g., `"session"`). + + - `const SessionSession Session = "session"` ### Example @@ -46093,49 +68614,39 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - skill, err := client.Beta.Skills.Delete( + fileMetadata, err := client.Beta.Files.GetMetadata( context.TODO(), - "skill_id", - anthropic.BetaSkillDeleteParams{ + "file_id", + anthropic.BetaFileGetMetadataParams{ }, ) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", skill.ID) + fmt.Printf("%+v\n", fileMetadata.ID) } ``` -# Versions - -## Create +## Delete -`client.Beta.Skills.Versions.New(ctx, skillID, params) (*BetaSkillVersionNewResponse, error)` +`client.Beta.Files.Delete(ctx, fileID, body) (*DeletedFile, error)` -**post** `/v1/skills/{skill_id}/versions` +**delete** `/v1/files/{file_id}` -Create Skill Version +Delete File ### Parameters -- `skillID string` - - Unique identifier for the skill. - - The format and length of IDs may change over time. - -- `params BetaSkillVersionNewParams` - - - `Files param.Field[[]Reader]` +- `fileID string` - Body param: Files to upload for the skill. + ID of the File. - All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. +- `body BetaFileDeleteParams` - `Betas param.Field[[]AnthropicBeta]` - Header param: Optional header to specify the beta version(s) you want to use. + Optional header to specify the beta version(s) you want to use. - `string` @@ -46183,55 +68694,21 @@ Create Skill Version - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaSkillVersionNewResponse struct{…}` +- `type DeletedFile struct{…}` - `ID string` - Unique identifier for the skill version. - - The format and length of IDs may change over time. - - - `CreatedAt string` - - ISO 8601 timestamp of when the skill version was created. - - - `Description string` - - Description of the skill version. - - This is extracted from the SKILL.md file in the skill upload. - - - `Directory string` - - Directory name of the skill version. - - This is the top-level directory name that was extracted from the uploaded files. - - - `Name string` - - Human-readable name of the skill version. - - This is extracted from the SKILL.md file in the skill upload. - - - `SkillID string` - - Identifier for the skill that this version belongs to. - - - `Type string` - - Object type. + ID of the deleted file. - For Skill Versions, this is always `"skill_version"`. + - `Type DeletedFileType` - - `Version string` + Deleted object type. - Version identifier for the skill. + For file deletion, this is always `"file_deleted"`. - Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + - `const DeletedFileTypeFileDeleted DeletedFileType = "file_deleted"` ### Example @@ -46250,47 +68727,129 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - version, err := client.Beta.Skills.Versions.New( + deletedFile, err := client.Beta.Files.Delete( context.TODO(), - "skill_id", - anthropic.BetaSkillVersionNewParams{ + "file_id", + anthropic.BetaFileDeleteParams{ }, ) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", version.ID) + fmt.Printf("%+v\n", deletedFile.ID) } ``` -## List +## Domain Types -`client.Beta.Skills.Versions.List(ctx, skillID, params) (*PageCursor[BetaSkillVersionListResponse], error)` +### Beta File Scope -**get** `/v1/skills/{skill_id}/versions` +- `type BetaFileScope struct{…}` -List Skill Versions + - `ID string` -### Parameters + The ID of the scoping resource (e.g., the session ID). -- `skillID string` + - `Type Session` - Unique identifier for the skill. + The type of scope (e.g., `"session"`). - The format and length of IDs may change over time. + - `const SessionSession Session = "session"` -- `params BetaSkillVersionListParams` +### Deleted File + +- `type DeletedFile struct{…}` + + - `ID string` + + ID of the deleted file. + + - `Type DeletedFileType` + + Deleted object type. + + For file deletion, this is always `"file_deleted"`. + + - `const DeletedFileTypeFileDeleted DeletedFileType = "file_deleted"` + +### File Metadata + +- `type FileMetadata struct{…}` + + - `ID string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `CreatedAt Time` + + RFC 3339 datetime string representing when the file was created. + + - `Filename string` + + Original filename of the uploaded file. + + - `MimeType string` + + MIME type of the file. + + - `SizeBytes int64` + + Size of the file in bytes. + + - `Type File` + + Object type. + + For files, this is always `"file"`. + + - `const FileFile File = "file"` + + - `Downloadable bool` + + Whether the file can be downloaded. + + - `Scope BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `ID string` + + The ID of the scoping resource (e.g., the session ID). + + - `Type Session` + + The type of scope (e.g., `"session"`). + + - `const SessionSession Session = "session"` + +# Skills + +## Create + +`client.Beta.Skills.New(ctx, params) (*BetaSkillNewResponse, error)` + +**post** `/v1/skills` + +Create Skill + +### Parameters + +- `params BetaSkillNewParams` + + - `DisplayTitle param.Field[string]` - - `Limit param.Field[int64]` + Body param: Display title for the skill. - Query param: Number of items to return per page. + This is a human-readable label that is not included in the prompt sent to the model. - Defaults to `20`. Ranges from `1` to `1000`. + - `Files param.Field[[]Reader]` - - `Page param.Field[string]` + Body param: Files to upload for the skill. - Query param: Optionally set to the `next_page` token from the previous response. + All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. - `Betas param.Field[[]AnthropicBeta]` @@ -46342,55 +68901,50 @@ List Skill Versions - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaSkillVersionListResponse struct{…}` +- `type BetaSkillNewResponse struct{…}` - `ID string` - Unique identifier for the skill version. + Unique identifier for the skill. The format and length of IDs may change over time. - `CreatedAt string` - ISO 8601 timestamp of when the skill version was created. - - - `Description string` + ISO 8601 timestamp of when the skill was created. - Description of the skill version. + - `DisplayTitle string` - This is extracted from the SKILL.md file in the skill upload. + Display title for the skill. - - `Directory string` + This is a human-readable label that is not included in the prompt sent to the model. - Directory name of the skill version. + - `LatestVersion string` - This is the top-level directory name that was extracted from the uploaded files. + The latest version identifier for the skill. - - `Name string` + This represents the most recent version of the skill that has been created. - Human-readable name of the skill version. + - `Source string` - This is extracted from the SKILL.md file in the skill upload. + Source of the skill. - - `SkillID string` + This may be one of the following values: - Identifier for the skill that this version belongs to. + * `"custom"`: the skill was created by a user + * `"anthropic"`: the skill was created by Anthropic - `Type string` Object type. - For Skill Versions, this is always `"skill_version"`. - - - `Version string` + For Skills, this is always `"skill"`. - Version identifier for the skill. + - `UpdatedAt string` - Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + ISO 8601 timestamp of when the skill was last updated. ### Example @@ -46409,43 +68963,48 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - page, err := client.Beta.Skills.Versions.List( - context.TODO(), - "skill_id", - anthropic.BetaSkillVersionListParams{ + skill, err := client.Beta.Skills.New(context.TODO(), anthropic.BetaSkillNewParams{ - }, - ) + }) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", page) + fmt.Printf("%+v\n", skill.ID) } ``` -## Retrieve +## List -`client.Beta.Skills.Versions.Get(ctx, version, params) (*BetaSkillVersionGetResponse, error)` +`client.Beta.Skills.List(ctx, params) (*PageCursor[BetaSkillListResponse], error)` -**get** `/v1/skills/{skill_id}/versions/{version}` +**get** `/v1/skills` -Get Skill Version +List Skills ### Parameters -- `version string` +- `params BetaSkillListParams` - Version identifier for the skill. + - `Limit param.Field[int64]` - Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + Query param: Number of results to return per page. -- `params BetaSkillVersionGetParams` + Maximum value is 100. Defaults to 20. - - `SkillID param.Field[string]` + - `Page param.Field[string]` - Path param: Unique identifier for the skill. + Query param: Pagination token for fetching a specific page of results. - The format and length of IDs may change over time. + Pass the value from a previous response's `next_page` field to get the next page of results. + + - `Source param.Field[string]` + + Query param: Filter skills by source. + + If provided, only skills from the specified source will be returned: + + * `"custom"`: only return user-created skills + * `"anthropic"`: only return Anthropic-created skills - `Betas param.Field[[]AnthropicBeta]` @@ -46497,55 +69056,50 @@ Get Skill Version - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaSkillVersionGetResponse struct{…}` +- `type BetaSkillListResponse struct{…}` - `ID string` - Unique identifier for the skill version. + Unique identifier for the skill. The format and length of IDs may change over time. - `CreatedAt string` - ISO 8601 timestamp of when the skill version was created. - - - `Description string` + ISO 8601 timestamp of when the skill was created. - Description of the skill version. + - `DisplayTitle string` - This is extracted from the SKILL.md file in the skill upload. + Display title for the skill. - - `Directory string` + This is a human-readable label that is not included in the prompt sent to the model. - Directory name of the skill version. + - `LatestVersion string` - This is the top-level directory name that was extracted from the uploaded files. + The latest version identifier for the skill. - - `Name string` + This represents the most recent version of the skill that has been created. - Human-readable name of the skill version. + - `Source string` - This is extracted from the SKILL.md file in the skill upload. + Source of the skill. - - `SkillID string` + This may be one of the following values: - Identifier for the skill that this version belongs to. + * `"custom"`: the skill was created by a user + * `"anthropic"`: the skill was created by Anthropic - `Type string` Object type. - For Skill Versions, this is always `"skill_version"`. - - - `Version string` + For Skills, this is always `"skill"`. - Version identifier for the skill. + - `UpdatedAt string` - Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + ISO 8601 timestamp of when the skill was last updated. ### Example @@ -46564,47 +69118,37 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - version, err := client.Beta.Skills.Versions.Get( - context.TODO(), - "version", - anthropic.BetaSkillVersionGetParams{ - SkillID: "skill_id", - }, - ) + page, err := client.Beta.Skills.List(context.TODO(), anthropic.BetaSkillListParams{ + + }) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", version.ID) + fmt.Printf("%+v\n", page) } ``` -## Delete +## Retrieve -`client.Beta.Skills.Versions.Delete(ctx, version, params) (*BetaSkillVersionDeleteResponse, error)` +`client.Beta.Skills.Get(ctx, skillID, query) (*BetaSkillGetResponse, error)` -**delete** `/v1/skills/{skill_id}/versions/{version}` +**get** `/v1/skills/{skill_id}` -Delete Skill Version +Get Skill ### Parameters -- `version string` - - Version identifier for the skill. - - Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - -- `params BetaSkillVersionDeleteParams` +- `skillID string` - - `SkillID param.Field[string]` + Unique identifier for the skill. - Path param: Unique identifier for the skill. + The format and length of IDs may change over time. - The format and length of IDs may change over time. +- `query BetaSkillGetParams` - `Betas param.Field[[]AnthropicBeta]` - Header param: Optional header to specify the beta version(s) you want to use. + Optional header to specify the beta version(s) you want to use. - `string` @@ -46652,23 +69196,50 @@ Delete Skill Version - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaSkillVersionDeleteResponse struct{…}` +- `type BetaSkillGetResponse struct{…}` - `ID string` - Version identifier for the skill. + Unique identifier for the skill. - Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + The format and length of IDs may change over time. + + - `CreatedAt string` + + ISO 8601 timestamp of when the skill was created. + + - `DisplayTitle string` + + Display title for the skill. + + This is a human-readable label that is not included in the prompt sent to the model. + + - `LatestVersion string` + + The latest version identifier for the skill. + + This represents the most recent version of the skill that has been created. + + - `Source string` + + Source of the skill. + + This may be one of the following values: + + * `"custom"`: the skill was created by a user + * `"anthropic"`: the skill was created by Anthropic - `Type string` - Deleted object type. + Object type. - For Skill Versions, this is always `"skill_version_deleted"`. + For Skills, this is always `"skill"`. + + - `UpdatedAt string` + + ISO 8601 timestamp of when the skill was last updated. ### Example @@ -46687,45 +69258,41 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - version, err := client.Beta.Skills.Versions.Delete( + skill, err := client.Beta.Skills.Get( context.TODO(), - "version", - anthropic.BetaSkillVersionDeleteParams{ - SkillID: "skill_id", + "skill_id", + anthropic.BetaSkillGetParams{ + }, ) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", version.ID) + fmt.Printf("%+v\n", skill.ID) } ``` -# User Profiles - -## Create +## Delete -`client.Beta.UserProfiles.New(ctx, params) (*BetaUserProfile, error)` +`client.Beta.Skills.Delete(ctx, skillID, body) (*BetaSkillDeleteResponse, error)` -**post** `/v1/user_profiles` +**delete** `/v1/skills/{skill_id}` -Create User Profile +Delete Skill ### Parameters -- `params BetaUserProfileNewParams` - - - `ExternalID param.Field[string]` +- `skillID string` - Body param + Unique identifier for the skill. - - `Metadata param.Field[map[string, string]]` + The format and length of IDs may change over time. - Body param: Free-form key-value data to attach to this user profile. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. Values must be non-empty strings. +- `body BetaSkillDeleteParams` - `Betas param.Field[[]AnthropicBeta]` - Header param: Optional header to specify the beta version(s) you want to use. + Optional header to specify the beta version(s) you want to use. - `string` @@ -46773,31 +69340,21 @@ Create User Profile - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaUserProfile struct{…}` +- `type BetaSkillDeleteResponse struct{…}` - `ID string` - - `CreatedAt Time` - - A timestamp in RFC 3339 format - - - `Metadata map[string, string]` - - - `TrustGrants map[string, BetaUserProfileTrustGrant]` + Unique identifier for the skill. - - `Status string` + The format and length of IDs may change over time. - `Type string` - - `UpdatedAt Time` - - A timestamp in RFC 3339 format + Deleted object type. - - `ExternalID string` + For Skills, this is always `"skill_deleted"`. ### Example @@ -46816,43 +69373,45 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - betaUserProfile, err := client.Beta.UserProfiles.New(context.TODO(), anthropic.BetaUserProfileNewParams{ + skill, err := client.Beta.Skills.Delete( + context.TODO(), + "skill_id", + anthropic.BetaSkillDeleteParams{ - }) + }, + ) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", betaUserProfile.ID) + fmt.Printf("%+v\n", skill.ID) } ``` -## List - -`client.Beta.UserProfiles.List(ctx, params) (*PageCursorV2[BetaUserProfile], error)` +# Versions -**get** `/v1/user_profiles` +## Create -List User Profiles +`client.Beta.Skills.Versions.New(ctx, skillID, params) (*BetaSkillVersionNewResponse, error)` -### Parameters +**post** `/v1/skills/{skill_id}/versions` -- `params BetaUserProfileListParams` +Create Skill Version - - `Limit param.Field[int64]` +### Parameters - Query param: Query parameter for limit +- `skillID string` - - `Order param.Field[BetaUserProfileListParamsOrder]` + Unique identifier for the skill. - Query param: Query parameter for order + The format and length of IDs may change over time. - - `const BetaUserProfileListParamsOrderAsc BetaUserProfileListParamsOrder = "asc"` +- `params BetaSkillVersionNewParams` - - `const BetaUserProfileListParamsOrderDesc BetaUserProfileListParamsOrder = "desc"` + - `Files param.Field[[]Reader]` - - `Page param.Field[string]` + Body param: Files to upload for the skill. - Query param: Query parameter for page + All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. - `Betas param.Field[[]AnthropicBeta]` @@ -46904,31 +69463,53 @@ List User Profiles - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaUserProfile struct{…}` +- `type BetaSkillVersionNewResponse struct{…}` - `ID string` - - `CreatedAt Time` + Unique identifier for the skill version. - A timestamp in RFC 3339 format + The format and length of IDs may change over time. - - `Metadata map[string, string]` + - `CreatedAt string` + + ISO 8601 timestamp of when the skill version was created. + + - `Description string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `Directory string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `Name string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. - - `TrustGrants map[string, BetaUserProfileTrustGrant]` + - `SkillID string` - - `Status string` + Identifier for the skill that this version belongs to. - `Type string` - - `UpdatedAt Time` + Object type. - A timestamp in RFC 3339 format + For Skill Versions, this is always `"skill_version"`. + + - `Version string` + + Version identifier for the skill. - - `ExternalID string` + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). ### Example @@ -46947,33 +69528,51 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - page, err := client.Beta.UserProfiles.List(context.TODO(), anthropic.BetaUserProfileListParams{ + version, err := client.Beta.Skills.Versions.New( + context.TODO(), + "skill_id", + anthropic.BetaSkillVersionNewParams{ - }) + }, + ) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", page) + fmt.Printf("%+v\n", version.ID) } ``` -## Retrieve +## List -`client.Beta.UserProfiles.Get(ctx, id, query) (*BetaUserProfile, error)` +`client.Beta.Skills.Versions.List(ctx, skillID, params) (*PageCursor[BetaSkillVersionListResponse], error)` -**get** `/v1/user_profiles/{id}` +**get** `/v1/skills/{skill_id}/versions` -Get User Profile +List Skill Versions ### Parameters -- `id string` +- `skillID string` + + Unique identifier for the skill. + + The format and length of IDs may change over time. + +- `params BetaSkillVersionListParams` + + - `Limit param.Field[int64]` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + + - `Page param.Field[string]` -- `query BetaUserProfileGetParams` + Query param: Optionally set to the `next_page` token from the previous response. - `Betas param.Field[[]AnthropicBeta]` - Optional header to specify the beta version(s) you want to use. + Header param: Optional header to specify the beta version(s) you want to use. - `string` @@ -47021,31 +69620,53 @@ Get User Profile - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaUserProfile struct{…}` +- `type BetaSkillVersionListResponse struct{…}` - `ID string` - - `CreatedAt Time` + Unique identifier for the skill version. - A timestamp in RFC 3339 format + The format and length of IDs may change over time. - - `Metadata map[string, string]` + - `CreatedAt string` + + ISO 8601 timestamp of when the skill version was created. + + - `Description string` - - `TrustGrants map[string, BetaUserProfileTrustGrant]` + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `Directory string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `Name string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `SkillID string` - - `Status string` + Identifier for the skill that this version belongs to. - `Type string` - - `UpdatedAt Time` + Object type. - A timestamp in RFC 3339 format + For Skill Versions, this is always `"skill_version"`. + + - `Version string` - - `ExternalID string` + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). ### Example @@ -47064,41 +69685,43 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - betaUserProfile, err := client.Beta.UserProfiles.Get( + page, err := client.Beta.Skills.Versions.List( context.TODO(), - "id", - anthropic.BetaUserProfileGetParams{ + "skill_id", + anthropic.BetaSkillVersionListParams{ }, ) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", betaUserProfile.ID) + fmt.Printf("%+v\n", page) } ``` -## Update +## Retrieve -`client.Beta.UserProfiles.Update(ctx, id, params) (*BetaUserProfile, error)` +`client.Beta.Skills.Versions.Get(ctx, version, params) (*BetaSkillVersionGetResponse, error)` -**post** `/v1/user_profiles/{id}` +**get** `/v1/skills/{skill_id}/versions/{version}` -Update User Profile +Get Skill Version ### Parameters -- `id string` +- `version string` + + Version identifier for the skill. -- `params BetaUserProfileUpdateParams` + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - - `ExternalID param.Field[string]` +- `params BetaSkillVersionGetParams` - Body param + - `SkillID param.Field[string]` - - `Metadata param.Field[map[string, string]]` + Path param: Unique identifier for the skill. - Body param: Key-value pairs to merge into the stored metadata. Keys provided overwrite existing values. To remove a key, set its value to an empty string. Keys not provided are left unchanged. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. + The format and length of IDs may change over time. - `Betas param.Field[[]AnthropicBeta]` @@ -47150,31 +69773,53 @@ Update User Profile - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaUserProfile struct{…}` +- `type BetaSkillVersionGetResponse struct{…}` - `ID string` - - `CreatedAt Time` + Unique identifier for the skill version. - A timestamp in RFC 3339 format + The format and length of IDs may change over time. - - `Metadata map[string, string]` + - `CreatedAt string` + + ISO 8601 timestamp of when the skill version was created. + + - `Description string` + + Description of the skill version. + + This is extracted from the SKILL.md file in the skill upload. + + - `Directory string` + + Directory name of the skill version. + + This is the top-level directory name that was extracted from the uploaded files. + + - `Name string` + + Human-readable name of the skill version. + + This is extracted from the SKILL.md file in the skill upload. - - `TrustGrants map[string, BetaUserProfileTrustGrant]` + - `SkillID string` - - `Status string` + Identifier for the skill that this version belongs to. - `Type string` - - `UpdatedAt Time` + Object type. - A timestamp in RFC 3339 format + For Skill Versions, this is always `"skill_version"`. + + - `Version string` + + Version identifier for the skill. - - `ExternalID string` + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). ### Example @@ -47193,37 +69838,47 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - betaUserProfile, err := client.Beta.UserProfiles.Update( + version, err := client.Beta.Skills.Versions.Get( context.TODO(), - "id", - anthropic.BetaUserProfileUpdateParams{ - + "version", + anthropic.BetaSkillVersionGetParams{ + SkillID: "skill_id", }, ) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", betaUserProfile.ID) + fmt.Printf("%+v\n", version.ID) } ``` -## Create Enrollment URL +## Delete -`client.Beta.UserProfiles.NewEnrollmentURL(ctx, id, body) (*BetaUserProfileEnrollmentURL, error)` +`client.Beta.Skills.Versions.Delete(ctx, version, params) (*BetaSkillVersionDeleteResponse, error)` -**post** `/v1/user_profiles/{id}/enrollment_url` +**delete** `/v1/skills/{skill_id}/versions/{version}` -Create Enrollment URL +Delete Skill Version ### Parameters -- `id string` +- `version string` + + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). + +- `params BetaSkillVersionDeleteParams` + + - `SkillID param.Field[string]` + + Path param: Unique identifier for the skill. -- `body BetaUserProfileNewEnrollmentURLParams` + The format and length of IDs may change over time. - `Betas param.Field[[]AnthropicBeta]` - Optional header to specify the beta version(s) you want to use. + Header param: Optional header to specify the beta version(s) you want to use. - `string` @@ -47271,19 +69926,21 @@ Create Enrollment URL - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns -- `type BetaUserProfileEnrollmentURL struct{…}` +- `type BetaSkillVersionDeleteResponse struct{…}` - - `ExpiresAt Time` + - `ID string` - A timestamp in RFC 3339 format + Version identifier for the skill. + + Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - `Type string` - - `URL string` + Deleted object type. + + For Skill Versions, this is always `"skill_version_deleted"`. ### Example @@ -47302,60 +69959,16 @@ func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) - betaUserProfileEnrollmentURL, err := client.Beta.UserProfiles.NewEnrollmentURL( + version, err := client.Beta.Skills.Versions.Delete( context.TODO(), - "id", - anthropic.BetaUserProfileNewEnrollmentURLParams{ - + "version", + anthropic.BetaSkillVersionDeleteParams{ + SkillID: "skill_id", }, ) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", betaUserProfileEnrollmentURL.ExpiresAt) + fmt.Printf("%+v\n", version.ID) } ``` - -## Domain Types - -### Beta User Profile - -- `type BetaUserProfile struct{…}` - - - `ID string` - - - `CreatedAt Time` - - A timestamp in RFC 3339 format - - - `Metadata map[string, string]` - - - `TrustGrants map[string, BetaUserProfileTrustGrant]` - - - `Status string` - - - `Type string` - - - `UpdatedAt Time` - - A timestamp in RFC 3339 format - - - `ExternalID string` - -### Beta User Profile Enrollment URL - -- `type BetaUserProfileEnrollmentURL struct{…}` - - - `ExpiresAt Time` - - A timestamp in RFC 3339 format - - - `Type string` - - - `URL string` - -### Beta User Profile Trust Grant - -- `type BetaUserProfileTrustGrant struct{…}` - - - `Status string` diff --git a/content/en/api/go/beta/agents.md b/content/en/api/go/beta/agents.md new file mode 100644 index 000000000..f4349d28d --- /dev/null +++ b/content/en/api/go/beta/agents.md @@ -0,0 +1,4324 @@ +# Agents + +## Create + +`client.Beta.Agents.New(ctx, params) (*BetaManagedAgentsAgent, error)` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `params BetaAgentNewParams` + + - `Model param.Field[BetaManagedAgentsModelConfigParamsResp]` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `type BetaManagedAgentsModelConfigParamsResp struct{…}` + + An object that defines additional configuration control over model use + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigParamsSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigParamsSpeedStandard BetaManagedAgentsModelConfigParamsSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigParamsSpeedFast BetaManagedAgentsModelConfigParamsSpeed = "fast"` + + - `Name param.Field[string]` + + Body param: Human-readable name for the agent. 1-256 characters. + + - `Description param.Field[string]` + + Body param: Description of what the agent does. Up to 2048 characters. + + - `MCPServers param.Field[[]BetaManagedAgentsURLMCPServerParamsResp]` + + Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `Name string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `Type BetaManagedAgentsURLMCPServerParamsType` + + - `const BetaManagedAgentsURLMCPServerParamsTypeURL BetaManagedAgentsURLMCPServerParamsType = "url"` + + - `URL string` + + Endpoint URL for the MCP server. + + - `Metadata param.Field[map[string, string]]` + + Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + + - `Skills param.Field[[]BetaManagedAgentsSkillParamsUnionResp]` + + Body param: Skills available to the agent. Maximum 20. + + - `type BetaManagedAgentsAnthropicSkillParamsResp struct{…}` + + An Anthropic-managed skill. + + - `SkillID string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `Type BetaManagedAgentsAnthropicSkillParamsType` + + - `const BetaManagedAgentsAnthropicSkillParamsTypeAnthropic BetaManagedAgentsAnthropicSkillParamsType = "anthropic"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + + - `type BetaManagedAgentsCustomSkillParamsResp struct{…}` + + A user-created custom skill. + + - `SkillID string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `Type BetaManagedAgentsCustomSkillParamsType` + + - `const BetaManagedAgentsCustomSkillParamsTypeCustom BetaManagedAgentsCustomSkillParamsType = "custom"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + + - `System param.Field[string]` + + Body param: System prompt for the agent. Up to 100,000 characters. + + - `Tools param.Field[[]BetaAgentNewParamsToolUnion]` + + Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `type BetaManagedAgentsAgentToolset20260401ParamsResp struct{…}` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `Type BetaManagedAgentsAgentToolset20260401ParamsType` + + - `const BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401ParamsType = "agent_toolset_20260401"` + + - `Configs []BetaManagedAgentsAgentToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name BetaManagedAgentsAgentToolConfigParamsName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigParamsNameBash BetaManagedAgentsAgentToolConfigParamsName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameEdit BetaManagedAgentsAgentToolConfigParamsName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameRead BetaManagedAgentsAgentToolConfigParamsName = "read"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWrite BetaManagedAgentsAgentToolConfigParamsName = "write"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGlob BetaManagedAgentsAgentToolConfigParamsName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGrep BetaManagedAgentsAgentToolConfigParamsName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebFetch BetaManagedAgentsAgentToolConfigParamsName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebSearch BetaManagedAgentsAgentToolConfigParamsName = "web_search"` + + - `Enabled bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfigParamsResp` + + Default configuration for all tools in a toolset. + + - `Enabled bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `type BetaManagedAgentsMCPToolsetParamsResp struct{…}` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `MCPServerName string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `Type BetaManagedAgentsMCPToolsetParamsType` + + - `const BetaManagedAgentsMCPToolsetParamsTypeMCPToolset BetaManagedAgentsMCPToolsetParamsType = "mcp_toolset"` + + - `Configs []BetaManagedAgentsMCPToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name string` + + Name of the MCP tool to configure. 1-128 characters. + + - `Enabled bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfigParamsResp` + + Default configuration for all tools from an MCP server. + + - `Enabled bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `type BetaManagedAgentsCustomToolParamsResp struct{…}` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `Description string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `Type BetaManagedAgentsCustomToolParamsType` + + - `const BetaManagedAgentsCustomToolParamsTypeCustom BetaManagedAgentsCustomToolParamsType = "custom"` + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsAgent, err := client.Beta.Agents.New(context.TODO(), anthropic.BetaAgentNewParams{ + Model: anthropic.BetaManagedAgentsModelConfigParams{ + ID: anthropic.BetaManagedAgentsModelClaudeOpus4_6, + }, + Name: "My First Agent", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsAgent.ID) +} +``` + +## List + +`client.Beta.Agents.List(ctx, params) (*PageCursor[BetaManagedAgentsAgent], error)` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `params BetaAgentListParams` + + - `CreatedAtGte param.Field[Time]` + + Query param: Return agents created at or after this time (inclusive). + + - `CreatedAtLte param.Field[Time]` + + Query param: Return agents created at or before this time (inclusive). + + - `IncludeArchived param.Field[bool]` + + Query param: Include archived agents in results. Defaults to false. + + - `Limit param.Field[int64]` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor from a previous response. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Agents.List(context.TODO(), anthropic.BetaAgentListParams{ + + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Agents.Get(ctx, agentID, params) (*BetaManagedAgentsAgent, error)` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `agentID string` + +- `params BetaAgentGetParams` + + - `Version param.Field[int64]` + + Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsAgent, err := client.Beta.Agents.Get( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentGetParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsAgent.ID) +} +``` + +## Update + +`client.Beta.Agents.Update(ctx, agentID, params) (*BetaManagedAgentsAgent, error)` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `agentID string` + +- `params BetaAgentUpdateParams` + + - `Version param.Field[int64]` + + Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + + - `Description param.Field[string]` + + Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + + - `MCPServers param.Field[[]BetaManagedAgentsURLMCPServerParamsResp]` + + Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `Name string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `Type BetaManagedAgentsURLMCPServerParamsType` + + - `const BetaManagedAgentsURLMCPServerParamsTypeURL BetaManagedAgentsURLMCPServerParamsType = "url"` + + - `URL string` + + Endpoint URL for the MCP server. + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + + - `Model param.Field[BetaManagedAgentsModelConfigParamsResp]` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `type BetaManagedAgentsModelConfigParamsResp struct{…}` + + An object that defines additional configuration control over model use + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigParamsSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigParamsSpeedStandard BetaManagedAgentsModelConfigParamsSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigParamsSpeedFast BetaManagedAgentsModelConfigParamsSpeed = "fast"` + + - `Name param.Field[string]` + + Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + + - `Skills param.Field[[]BetaManagedAgentsSkillParamsUnionResp]` + + Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `type BetaManagedAgentsAnthropicSkillParamsResp struct{…}` + + An Anthropic-managed skill. + + - `SkillID string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `Type BetaManagedAgentsAnthropicSkillParamsType` + + - `const BetaManagedAgentsAnthropicSkillParamsTypeAnthropic BetaManagedAgentsAnthropicSkillParamsType = "anthropic"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + + - `type BetaManagedAgentsCustomSkillParamsResp struct{…}` + + A user-created custom skill. + + - `SkillID string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `Type BetaManagedAgentsCustomSkillParamsType` + + - `const BetaManagedAgentsCustomSkillParamsTypeCustom BetaManagedAgentsCustomSkillParamsType = "custom"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + + - `System param.Field[string]` + + Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + + - `Tools param.Field[[]BetaAgentUpdateParamsToolUnion]` + + Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `type BetaManagedAgentsAgentToolset20260401ParamsResp struct{…}` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `Type BetaManagedAgentsAgentToolset20260401ParamsType` + + - `const BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401ParamsType = "agent_toolset_20260401"` + + - `Configs []BetaManagedAgentsAgentToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name BetaManagedAgentsAgentToolConfigParamsName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigParamsNameBash BetaManagedAgentsAgentToolConfigParamsName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameEdit BetaManagedAgentsAgentToolConfigParamsName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameRead BetaManagedAgentsAgentToolConfigParamsName = "read"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWrite BetaManagedAgentsAgentToolConfigParamsName = "write"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGlob BetaManagedAgentsAgentToolConfigParamsName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGrep BetaManagedAgentsAgentToolConfigParamsName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebFetch BetaManagedAgentsAgentToolConfigParamsName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebSearch BetaManagedAgentsAgentToolConfigParamsName = "web_search"` + + - `Enabled bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfigParamsResp` + + Default configuration for all tools in a toolset. + + - `Enabled bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `type BetaManagedAgentsMCPToolsetParamsResp struct{…}` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `MCPServerName string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `Type BetaManagedAgentsMCPToolsetParamsType` + + - `const BetaManagedAgentsMCPToolsetParamsTypeMCPToolset BetaManagedAgentsMCPToolsetParamsType = "mcp_toolset"` + + - `Configs []BetaManagedAgentsMCPToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name string` + + Name of the MCP tool to configure. 1-128 characters. + + - `Enabled bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfigParamsResp` + + Default configuration for all tools from an MCP server. + + - `Enabled bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `type BetaManagedAgentsCustomToolParamsResp struct{…}` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `Description string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `Type BetaManagedAgentsCustomToolParamsType` + + - `const BetaManagedAgentsCustomToolParamsTypeCustom BetaManagedAgentsCustomToolParamsType = "custom"` + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsAgent, err := client.Beta.Agents.Update( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentUpdateParams{ + Version: 1, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsAgent.ID) +} +``` + +## Archive + +`client.Beta.Agents.Archive(ctx, agentID, body) (*BetaManagedAgentsAgent, error)` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `agentID string` + +- `body BetaAgentArchiveParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsAgent, err := client.Beta.Agents.Archive( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentArchiveParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsAgent.ID) +} +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `type BetaManagedAgentsAgentToolConfig struct{…}` + + Configuration for a specific agent tool. + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Agent Tool Config Params + +- `type BetaManagedAgentsAgentToolConfigParamsResp struct{…}` + + Configuration override for a specific tool within a toolset. + + - `Name BetaManagedAgentsAgentToolConfigParamsName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigParamsNameBash BetaManagedAgentsAgentToolConfigParamsName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameEdit BetaManagedAgentsAgentToolConfigParamsName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameRead BetaManagedAgentsAgentToolConfigParamsName = "read"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWrite BetaManagedAgentsAgentToolConfigParamsName = "write"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGlob BetaManagedAgentsAgentToolConfigParamsName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGrep BetaManagedAgentsAgentToolConfigParamsName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebFetch BetaManagedAgentsAgentToolConfigParamsName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebSearch BetaManagedAgentsAgentToolConfigParamsName = "web_search"` + + - `Enabled bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Agent Toolset Default Config + +- `type BetaManagedAgentsAgentToolsetDefaultConfig struct{…}` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `type BetaManagedAgentsAgentToolsetDefaultConfigParamsResp struct{…}` + + Default configuration for all tools in a toolset. + + - `Enabled bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Agent Toolset20260401 + +- `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `type BetaManagedAgentsAgentToolset20260401ParamsResp struct{…}` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `Type BetaManagedAgentsAgentToolset20260401ParamsType` + + - `const BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401ParamsType = "agent_toolset_20260401"` + + - `Configs []BetaManagedAgentsAgentToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name BetaManagedAgentsAgentToolConfigParamsName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigParamsNameBash BetaManagedAgentsAgentToolConfigParamsName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameEdit BetaManagedAgentsAgentToolConfigParamsName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameRead BetaManagedAgentsAgentToolConfigParamsName = "read"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWrite BetaManagedAgentsAgentToolConfigParamsName = "write"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGlob BetaManagedAgentsAgentToolConfigParamsName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGrep BetaManagedAgentsAgentToolConfigParamsName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebFetch BetaManagedAgentsAgentToolConfigParamsName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebSearch BetaManagedAgentsAgentToolConfigParamsName = "web_search"` + + - `Enabled bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfigParamsResp` + + Default configuration for all tools in a toolset. + + - `Enabled bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Always Allow Policy + +- `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + +### Beta Managed Agents Always Ask Policy + +- `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Anthropic Skill + +- `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + +### Beta Managed Agents Anthropic Skill Params + +- `type BetaManagedAgentsAnthropicSkillParamsResp struct{…}` + + An Anthropic-managed skill. + + - `SkillID string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `Type BetaManagedAgentsAnthropicSkillParamsType` + + - `const BetaManagedAgentsAnthropicSkillParamsTypeAnthropic BetaManagedAgentsAnthropicSkillParamsType = "anthropic"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + +### Beta Managed Agents Custom Skill Params + +- `type BetaManagedAgentsCustomSkillParamsResp struct{…}` + + A user-created custom skill. + + - `SkillID string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `Type BetaManagedAgentsCustomSkillParamsType` + + - `const BetaManagedAgentsCustomSkillParamsTypeCustom BetaManagedAgentsCustomSkillParamsType = "custom"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + +### Beta Managed Agents Custom Tool Input Schema + +- `type BetaManagedAgentsCustomToolInputSchema struct{…}` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + +### Beta Managed Agents Custom Tool Params + +- `type BetaManagedAgentsCustomToolParamsResp struct{…}` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `Description string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `Type BetaManagedAgentsCustomToolParamsType` + + - `const BetaManagedAgentsCustomToolParamsTypeCustom BetaManagedAgentsCustomToolParamsType = "custom"` + +### Beta Managed Agents MCP Server URL Definition + +- `type BetaManagedAgentsMCPServerURLDefinition struct{…}` + + URL-based MCP server connection as returned in API responses. + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + +### Beta Managed Agents MCP Tool Config + +- `type BetaManagedAgentsMCPToolConfig struct{…}` + + Resolved configuration for a specific MCP tool. + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents MCP Tool Config Params + +- `type BetaManagedAgentsMCPToolConfigParamsResp struct{…}` + + Configuration override for a specific MCP tool. + + - `Name string` + + Name of the MCP tool to configure. 1-128 characters. + + - `Enabled bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents MCP Toolset + +- `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + +### Beta Managed Agents MCP Toolset Default Config + +- `type BetaManagedAgentsMCPToolsetDefaultConfig struct{…}` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `type BetaManagedAgentsMCPToolsetDefaultConfigParamsResp struct{…}` + + Default configuration for all tools from an MCP server. + + - `Enabled bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents MCP Toolset Params + +- `type BetaManagedAgentsMCPToolsetParamsResp struct{…}` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `MCPServerName string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `Type BetaManagedAgentsMCPToolsetParamsType` + + - `const BetaManagedAgentsMCPToolsetParamsTypeMCPToolset BetaManagedAgentsMCPToolsetParamsType = "mcp_toolset"` + + - `Configs []BetaManagedAgentsMCPToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name string` + + Name of the MCP tool to configure. 1-128 characters. + + - `Enabled bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfigParamsResp` + + Default configuration for all tools from an MCP server. + + - `Enabled bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + +### Beta Managed Agents Model + +- `type BetaManagedAgentsModel interface{…}` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + +### Beta Managed Agents Model Config + +- `type BetaManagedAgentsModelConfig struct{…}` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + +### Beta Managed Agents Model Config Params + +- `type BetaManagedAgentsModelConfigParamsResp struct{…}` + + An object that defines additional configuration control over model use + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigParamsSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigParamsSpeedStandard BetaManagedAgentsModelConfigParamsSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigParamsSpeedFast BetaManagedAgentsModelConfigParamsSpeed = "fast"` + +### Beta Managed Agents Skill Params + +- `type BetaManagedAgentsSkillParamsUnionResp interface{…}` + + Skill to load in the session container. + + - `type BetaManagedAgentsAnthropicSkillParamsResp struct{…}` + + An Anthropic-managed skill. + + - `SkillID string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `Type BetaManagedAgentsAnthropicSkillParamsType` + + - `const BetaManagedAgentsAnthropicSkillParamsTypeAnthropic BetaManagedAgentsAnthropicSkillParamsType = "anthropic"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + + - `type BetaManagedAgentsCustomSkillParamsResp struct{…}` + + A user-created custom skill. + + - `SkillID string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `Type BetaManagedAgentsCustomSkillParamsType` + + - `const BetaManagedAgentsCustomSkillParamsTypeCustom BetaManagedAgentsCustomSkillParamsType = "custom"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `type BetaManagedAgentsURLMCPServerParamsResp struct{…}` + + URL-based MCP server connection. + + - `Name string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `Type BetaManagedAgentsURLMCPServerParamsType` + + - `const BetaManagedAgentsURLMCPServerParamsTypeURL BetaManagedAgentsURLMCPServerParamsType = "url"` + + - `URL string` + + Endpoint URL for the MCP server. + +# Versions + +## List + +`client.Beta.Agents.Versions.List(ctx, agentID, params) (*PageCursor[BetaManagedAgentsAgent], error)` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agentID string` + +- `params BetaAgentVersionListParams` + + - `Limit param.Field[int64]` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Agents.Versions.List( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentVersionListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` diff --git a/content/en/api/go/beta/agents/archive.md b/content/en/api/go/beta/agents/archive.md new file mode 100644 index 000000000..934a57009 --- /dev/null +++ b/content/en/api/go/beta/agents/archive.md @@ -0,0 +1,392 @@ +## Archive + +`client.Beta.Agents.Archive(ctx, agentID, body) (*BetaManagedAgentsAgent, error)` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `agentID string` + +- `body BetaAgentArchiveParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsAgent, err := client.Beta.Agents.Archive( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentArchiveParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsAgent.ID) +} +``` diff --git a/content/en/api/go/beta/agents/create.md b/content/en/api/go/beta/agents/create.md new file mode 100644 index 000000000..126958857 --- /dev/null +++ b/content/en/api/go/beta/agents/create.md @@ -0,0 +1,713 @@ +## Create + +`client.Beta.Agents.New(ctx, params) (*BetaManagedAgentsAgent, error)` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `params BetaAgentNewParams` + + - `Model param.Field[BetaManagedAgentsModelConfigParamsResp]` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `type BetaManagedAgentsModelConfigParamsResp struct{…}` + + An object that defines additional configuration control over model use + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigParamsSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigParamsSpeedStandard BetaManagedAgentsModelConfigParamsSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigParamsSpeedFast BetaManagedAgentsModelConfigParamsSpeed = "fast"` + + - `Name param.Field[string]` + + Body param: Human-readable name for the agent. 1-256 characters. + + - `Description param.Field[string]` + + Body param: Description of what the agent does. Up to 2048 characters. + + - `MCPServers param.Field[[]BetaManagedAgentsURLMCPServerParamsResp]` + + Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `Name string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `Type BetaManagedAgentsURLMCPServerParamsType` + + - `const BetaManagedAgentsURLMCPServerParamsTypeURL BetaManagedAgentsURLMCPServerParamsType = "url"` + + - `URL string` + + Endpoint URL for the MCP server. + + - `Metadata param.Field[map[string, string]]` + + Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + + - `Skills param.Field[[]BetaManagedAgentsSkillParamsUnionResp]` + + Body param: Skills available to the agent. Maximum 20. + + - `type BetaManagedAgentsAnthropicSkillParamsResp struct{…}` + + An Anthropic-managed skill. + + - `SkillID string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `Type BetaManagedAgentsAnthropicSkillParamsType` + + - `const BetaManagedAgentsAnthropicSkillParamsTypeAnthropic BetaManagedAgentsAnthropicSkillParamsType = "anthropic"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + + - `type BetaManagedAgentsCustomSkillParamsResp struct{…}` + + A user-created custom skill. + + - `SkillID string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `Type BetaManagedAgentsCustomSkillParamsType` + + - `const BetaManagedAgentsCustomSkillParamsTypeCustom BetaManagedAgentsCustomSkillParamsType = "custom"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + + - `System param.Field[string]` + + Body param: System prompt for the agent. Up to 100,000 characters. + + - `Tools param.Field[[]BetaAgentNewParamsToolUnion]` + + Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `type BetaManagedAgentsAgentToolset20260401ParamsResp struct{…}` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `Type BetaManagedAgentsAgentToolset20260401ParamsType` + + - `const BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401ParamsType = "agent_toolset_20260401"` + + - `Configs []BetaManagedAgentsAgentToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name BetaManagedAgentsAgentToolConfigParamsName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigParamsNameBash BetaManagedAgentsAgentToolConfigParamsName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameEdit BetaManagedAgentsAgentToolConfigParamsName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameRead BetaManagedAgentsAgentToolConfigParamsName = "read"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWrite BetaManagedAgentsAgentToolConfigParamsName = "write"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGlob BetaManagedAgentsAgentToolConfigParamsName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGrep BetaManagedAgentsAgentToolConfigParamsName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebFetch BetaManagedAgentsAgentToolConfigParamsName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebSearch BetaManagedAgentsAgentToolConfigParamsName = "web_search"` + + - `Enabled bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfigParamsResp` + + Default configuration for all tools in a toolset. + + - `Enabled bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `type BetaManagedAgentsMCPToolsetParamsResp struct{…}` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `MCPServerName string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `Type BetaManagedAgentsMCPToolsetParamsType` + + - `const BetaManagedAgentsMCPToolsetParamsTypeMCPToolset BetaManagedAgentsMCPToolsetParamsType = "mcp_toolset"` + + - `Configs []BetaManagedAgentsMCPToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name string` + + Name of the MCP tool to configure. 1-128 characters. + + - `Enabled bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfigParamsResp` + + Default configuration for all tools from an MCP server. + + - `Enabled bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `type BetaManagedAgentsCustomToolParamsResp struct{…}` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `Description string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `Type BetaManagedAgentsCustomToolParamsType` + + - `const BetaManagedAgentsCustomToolParamsTypeCustom BetaManagedAgentsCustomToolParamsType = "custom"` + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsAgent, err := client.Beta.Agents.New(context.TODO(), anthropic.BetaAgentNewParams{ + Model: anthropic.BetaManagedAgentsModelConfigParams{ + ID: anthropic.BetaManagedAgentsModelClaudeOpus4_6, + }, + Name: "My First Agent", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsAgent.ID) +} +``` diff --git a/content/en/api/go/beta/agents/list.md b/content/en/api/go/beta/agents/list.md new file mode 100644 index 000000000..f4179ad52 --- /dev/null +++ b/content/en/api/go/beta/agents/list.md @@ -0,0 +1,406 @@ +## List + +`client.Beta.Agents.List(ctx, params) (*PageCursor[BetaManagedAgentsAgent], error)` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `params BetaAgentListParams` + + - `CreatedAtGte param.Field[Time]` + + Query param: Return agents created at or after this time (inclusive). + + - `CreatedAtLte param.Field[Time]` + + Query param: Return agents created at or before this time (inclusive). + + - `IncludeArchived param.Field[bool]` + + Query param: Include archived agents in results. Defaults to false. + + - `Limit param.Field[int64]` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor from a previous response. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Agents.List(context.TODO(), anthropic.BetaAgentListParams{ + + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` diff --git a/content/en/api/go/beta/agents/retrieve.md b/content/en/api/go/beta/agents/retrieve.md new file mode 100644 index 000000000..2545765bf --- /dev/null +++ b/content/en/api/go/beta/agents/retrieve.md @@ -0,0 +1,396 @@ +## Retrieve + +`client.Beta.Agents.Get(ctx, agentID, params) (*BetaManagedAgentsAgent, error)` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `agentID string` + +- `params BetaAgentGetParams` + + - `Version param.Field[int64]` + + Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsAgent, err := client.Beta.Agents.Get( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentGetParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsAgent.ID) +} +``` diff --git a/content/en/api/go/beta/agents/update.md b/content/en/api/go/beta/agents/update.md new file mode 100644 index 000000000..d3d60b703 --- /dev/null +++ b/content/en/api/go/beta/agents/update.md @@ -0,0 +1,720 @@ +## Update + +`client.Beta.Agents.Update(ctx, agentID, params) (*BetaManagedAgentsAgent, error)` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `agentID string` + +- `params BetaAgentUpdateParams` + + - `Version param.Field[int64]` + + Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + + - `Description param.Field[string]` + + Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + + - `MCPServers param.Field[[]BetaManagedAgentsURLMCPServerParamsResp]` + + Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `Name string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `Type BetaManagedAgentsURLMCPServerParamsType` + + - `const BetaManagedAgentsURLMCPServerParamsTypeURL BetaManagedAgentsURLMCPServerParamsType = "url"` + + - `URL string` + + Endpoint URL for the MCP server. + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + + - `Model param.Field[BetaManagedAgentsModelConfigParamsResp]` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `type BetaManagedAgentsModelConfigParamsResp struct{…}` + + An object that defines additional configuration control over model use + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigParamsSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigParamsSpeedStandard BetaManagedAgentsModelConfigParamsSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigParamsSpeedFast BetaManagedAgentsModelConfigParamsSpeed = "fast"` + + - `Name param.Field[string]` + + Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + + - `Skills param.Field[[]BetaManagedAgentsSkillParamsUnionResp]` + + Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `type BetaManagedAgentsAnthropicSkillParamsResp struct{…}` + + An Anthropic-managed skill. + + - `SkillID string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `Type BetaManagedAgentsAnthropicSkillParamsType` + + - `const BetaManagedAgentsAnthropicSkillParamsTypeAnthropic BetaManagedAgentsAnthropicSkillParamsType = "anthropic"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + + - `type BetaManagedAgentsCustomSkillParamsResp struct{…}` + + A user-created custom skill. + + - `SkillID string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `Type BetaManagedAgentsCustomSkillParamsType` + + - `const BetaManagedAgentsCustomSkillParamsTypeCustom BetaManagedAgentsCustomSkillParamsType = "custom"` + + - `Version string` + + Version to pin. Defaults to latest if omitted. + + - `System param.Field[string]` + + Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + + - `Tools param.Field[[]BetaAgentUpdateParamsToolUnion]` + + Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `type BetaManagedAgentsAgentToolset20260401ParamsResp struct{…}` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `Type BetaManagedAgentsAgentToolset20260401ParamsType` + + - `const BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401ParamsType = "agent_toolset_20260401"` + + - `Configs []BetaManagedAgentsAgentToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name BetaManagedAgentsAgentToolConfigParamsName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigParamsNameBash BetaManagedAgentsAgentToolConfigParamsName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameEdit BetaManagedAgentsAgentToolConfigParamsName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameRead BetaManagedAgentsAgentToolConfigParamsName = "read"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWrite BetaManagedAgentsAgentToolConfigParamsName = "write"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGlob BetaManagedAgentsAgentToolConfigParamsName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameGrep BetaManagedAgentsAgentToolConfigParamsName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebFetch BetaManagedAgentsAgentToolConfigParamsName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigParamsNameWebSearch BetaManagedAgentsAgentToolConfigParamsName = "web_search"` + + - `Enabled bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfigParamsResp` + + Default configuration for all tools in a toolset. + + - `Enabled bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `type BetaManagedAgentsMCPToolsetParamsResp struct{…}` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `MCPServerName string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `Type BetaManagedAgentsMCPToolsetParamsType` + + - `const BetaManagedAgentsMCPToolsetParamsTypeMCPToolset BetaManagedAgentsMCPToolsetParamsType = "mcp_toolset"` + + - `Configs []BetaManagedAgentsMCPToolConfigParamsResp` + + Per-tool configuration overrides. + + - `Name string` + + Name of the MCP tool to configure. 1-128 characters. + + - `Enabled bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfigParamsResp` + + Default configuration for all tools from an MCP server. + + - `Enabled bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnionResp` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `type BetaManagedAgentsCustomToolParamsResp struct{…}` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `Description string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `Type BetaManagedAgentsCustomToolParamsType` + + - `const BetaManagedAgentsCustomToolParamsTypeCustom BetaManagedAgentsCustomToolParamsType = "custom"` + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsAgent, err := client.Beta.Agents.Update( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentUpdateParams{ + Version: 1, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsAgent.ID) +} +``` diff --git a/content/en/api/go/beta/agents/versions.md b/content/en/api/go/beta/agents/versions.md new file mode 100644 index 000000000..11d87b4ab --- /dev/null +++ b/content/en/api/go/beta/agents/versions.md @@ -0,0 +1,402 @@ +# Versions + +## List + +`client.Beta.Agents.Versions.List(ctx, agentID, params) (*PageCursor[BetaManagedAgentsAgent], error)` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agentID string` + +- `params BetaAgentVersionListParams` + + - `Limit param.Field[int64]` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Agents.Versions.List( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentVersionListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` diff --git a/content/en/api/go/beta/agents/versions/list.md b/content/en/api/go/beta/agents/versions/list.md new file mode 100644 index 000000000..b8af24043 --- /dev/null +++ b/content/en/api/go/beta/agents/versions/list.md @@ -0,0 +1,400 @@ +## List + +`client.Beta.Agents.Versions.List(ctx, agentID, params) (*PageCursor[BetaManagedAgentsAgent], error)` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agentID string` + +- `params BetaAgentVersionListParams` + + - `Limit param.Field[int64]` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsAgent struct{…}` + + A Managed Agents `agent`. + + - `ID string` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Metadata map[string, string]` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsAgentType` + + - `const BetaManagedAgentsAgentTypeAgent BetaManagedAgentsAgentType = "agent"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Version int64` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Agents.Versions.List( + context.TODO(), + "agent_011CZkYpogX7uDKUyvBTophP", + anthropic.BetaAgentVersionListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` diff --git a/content/en/api/go/beta/environments.md b/content/en/api/go/beta/environments.md new file mode 100644 index 000000000..ceef51481 --- /dev/null +++ b/content/en/api/go/beta/environments.md @@ -0,0 +1,1672 @@ +# Environments + +## Create + +`client.Beta.Environments.New(ctx, params) (*BetaEnvironment, error)` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `params BetaEnvironmentNewParams` + + - `Name param.Field[string]` + + Body param: Human-readable name for the environment + + - `Config param.Field[BetaCloudConfigParamsResp]` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Description param.Field[string]` + + Body param: Optional description of the environment + + - `Metadata param.Field[map[string, string]]` + + Body param: User-provided metadata key-value pairs + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironment, err := client.Beta.Environments.New(context.TODO(), anthropic.BetaEnvironmentNewParams{ + Name: "python-data-analysis", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironment.ID) +} +``` + +## List + +`client.Beta.Environments.List(ctx, params) (*PageCursor[BetaEnvironment], error)` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `params BetaEnvironmentListParams` + + - `IncludeArchived param.Field[bool]` + + Query param: Include archived environments in the response + + - `Limit param.Field[int64]` + + Query param: Maximum number of environments to return + + - `Page param.Field[string]` + + Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Environments.List(context.TODO(), anthropic.BetaEnvironmentListParams{ + + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Environments.Get(ctx, environmentID, query) (*BetaEnvironment, error)` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `environmentID string` + +- `query BetaEnvironmentGetParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironment, err := client.Beta.Environments.Get( + context.TODO(), + "env_011CZkZ9X2dpNyB7HsEFoRfW", + anthropic.BetaEnvironmentGetParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironment.ID) +} +``` + +## Update + +`client.Beta.Environments.Update(ctx, environmentID, params) (*BetaEnvironment, error)` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `environmentID string` + +- `params BetaEnvironmentUpdateParams` + + - `Config param.Field[BetaCloudConfigParamsResp]` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Description param.Field[string]` + + Body param: Updated description of the environment + + - `Metadata param.Field[map[string, string]]` + + Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + + - `Name param.Field[string]` + + Body param: Updated name for the environment + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironment, err := client.Beta.Environments.Update( + context.TODO(), + "env_011CZkZ9X2dpNyB7HsEFoRfW", + anthropic.BetaEnvironmentUpdateParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironment.ID) +} +``` + +## Delete + +`client.Beta.Environments.Delete(ctx, environmentID, body) (*BetaEnvironmentDeleteResponse, error)` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `environmentID string` + +- `body BetaEnvironmentDeleteParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironmentDeleteResponse struct{…}` + + Response after deleting an environment. + + - `ID string` + + Environment identifier + + - `Type EnvironmentDeleted` + + The type of response + + - `const EnvironmentDeletedEnvironmentDeleted EnvironmentDeleted = "environment_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironmentDeleteResponse, err := client.Beta.Environments.Delete( + context.TODO(), + "env_011CZkZ9X2dpNyB7HsEFoRfW", + anthropic.BetaEnvironmentDeleteParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironmentDeleteResponse.ID) +} +``` + +## Archive + +`client.Beta.Environments.Archive(ctx, environmentID, body) (*BetaEnvironment, error)` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `environmentID string` + +- `body BetaEnvironmentArchiveParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironment, err := client.Beta.Environments.Archive( + context.TODO(), + "env_011CZkZ9X2dpNyB7HsEFoRfW", + anthropic.BetaEnvironmentArchiveParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironment.ID) +} +``` + +## Domain Types + +### Beta Cloud Config + +- `type BetaCloudConfig struct{…}` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + +### Beta Cloud Config Params + +- `type BetaCloudConfigParamsResp struct{…}` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `Networking BetaCloudConfigParamsNetworkingUnionResp` + + Network configuration policy. Omit on update to preserve the existing value. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetworkParamsResp struct{…}` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Packages BetaPackagesParamsResp` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesParamsType` + + Package configuration type + + - `const BetaPackagesParamsTypePackages BetaPackagesParamsType = "packages"` + +### Beta Environment + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `type BetaEnvironmentDeleteResponse struct{…}` + + Response after deleting an environment. + + - `ID string` + + Environment identifier + + - `Type EnvironmentDeleted` + + The type of response + + - `const EnvironmentDeletedEnvironmentDeleted EnvironmentDeleted = "environment_deleted"` + +### Beta Limited Network + +- `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + +### Beta Limited Network Params + +- `type BetaLimitedNetworkParamsResp struct{…}` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + +### Beta Packages + +- `type BetaPackages struct{…}` + + Packages (and their versions) available in this environment. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + +### Beta Packages Params + +- `type BetaPackagesParamsResp struct{…}` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesParamsType` + + Package configuration type + + - `const BetaPackagesParamsTypePackages BetaPackagesParamsType = "packages"` + +### Beta Unrestricted Network + +- `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` diff --git a/content/en/api/go/beta/environments/archive.md b/content/en/api/go/beta/environments/archive.md new file mode 100644 index 000000000..abcc9caa8 --- /dev/null +++ b/content/en/api/go/beta/environments/archive.md @@ -0,0 +1,214 @@ +## Archive + +`client.Beta.Environments.Archive(ctx, environmentID, body) (*BetaEnvironment, error)` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `environmentID string` + +- `body BetaEnvironmentArchiveParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironment, err := client.Beta.Environments.Archive( + context.TODO(), + "env_011CZkZ9X2dpNyB7HsEFoRfW", + anthropic.BetaEnvironmentArchiveParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironment.ID) +} +``` diff --git a/content/en/api/go/beta/environments/create.md b/content/en/api/go/beta/environments/create.md new file mode 100644 index 000000000..fe9e2f3fe --- /dev/null +++ b/content/en/api/go/beta/environments/create.md @@ -0,0 +1,227 @@ +## Create + +`client.Beta.Environments.New(ctx, params) (*BetaEnvironment, error)` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `params BetaEnvironmentNewParams` + + - `Name param.Field[string]` + + Body param: Human-readable name for the environment + + - `Config param.Field[BetaCloudConfigParamsResp]` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Description param.Field[string]` + + Body param: Optional description of the environment + + - `Metadata param.Field[map[string, string]]` + + Body param: User-provided metadata key-value pairs + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironment, err := client.Beta.Environments.New(context.TODO(), anthropic.BetaEnvironmentNewParams{ + Name: "python-data-analysis", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironment.ID) +} +``` diff --git a/content/en/api/go/beta/environments/delete.md b/content/en/api/go/beta/environments/delete.md new file mode 100644 index 000000000..abf66b1ad --- /dev/null +++ b/content/en/api/go/beta/environments/delete.md @@ -0,0 +1,110 @@ +## Delete + +`client.Beta.Environments.Delete(ctx, environmentID, body) (*BetaEnvironmentDeleteResponse, error)` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `environmentID string` + +- `body BetaEnvironmentDeleteParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironmentDeleteResponse struct{…}` + + Response after deleting an environment. + + - `ID string` + + Environment identifier + + - `Type EnvironmentDeleted` + + The type of response + + - `const EnvironmentDeletedEnvironmentDeleted EnvironmentDeleted = "environment_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironmentDeleteResponse, err := client.Beta.Environments.Delete( + context.TODO(), + "env_011CZkZ9X2dpNyB7HsEFoRfW", + anthropic.BetaEnvironmentDeleteParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironmentDeleteResponse.ID) +} +``` diff --git a/content/en/api/go/beta/environments/list.md b/content/en/api/go/beta/environments/list.md new file mode 100644 index 000000000..4bb75063e --- /dev/null +++ b/content/en/api/go/beta/environments/list.md @@ -0,0 +1,220 @@ +## List + +`client.Beta.Environments.List(ctx, params) (*PageCursor[BetaEnvironment], error)` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `params BetaEnvironmentListParams` + + - `IncludeArchived param.Field[bool]` + + Query param: Include archived environments in the response + + - `Limit param.Field[int64]` + + Query param: Maximum number of environments to return + + - `Page param.Field[string]` + + Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Environments.List(context.TODO(), anthropic.BetaEnvironmentListParams{ + + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` diff --git a/content/en/api/go/beta/environments/retrieve.md b/content/en/api/go/beta/environments/retrieve.md new file mode 100644 index 000000000..d9a4073c1 --- /dev/null +++ b/content/en/api/go/beta/environments/retrieve.md @@ -0,0 +1,214 @@ +## Retrieve + +`client.Beta.Environments.Get(ctx, environmentID, query) (*BetaEnvironment, error)` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `environmentID string` + +- `query BetaEnvironmentGetParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironment, err := client.Beta.Environments.Get( + context.TODO(), + "env_011CZkZ9X2dpNyB7HsEFoRfW", + anthropic.BetaEnvironmentGetParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironment.ID) +} +``` diff --git a/content/en/api/go/beta/environments/update.md b/content/en/api/go/beta/environments/update.md new file mode 100644 index 000000000..498866702 --- /dev/null +++ b/content/en/api/go/beta/environments/update.md @@ -0,0 +1,233 @@ +## Update + +`client.Beta.Environments.Update(ctx, environmentID, params) (*BetaEnvironment, error)` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `environmentID string` + +- `params BetaEnvironmentUpdateParams` + + - `Config param.Field[BetaCloudConfigParamsResp]` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Description param.Field[string]` + + Body param: Updated description of the environment + + - `Metadata param.Field[map[string, string]]` + + Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + + - `Name param.Field[string]` + + Body param: Updated name for the environment + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaEnvironment struct{…}` + + Unified Environment resource for both cloud and BYOC environments. + + - `ID string` + + Environment identifier (e.g., 'env_...') + + - `ArchivedAt string` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `Config BetaCloudConfig` + + `cloud` environment configuration. + + - `Networking BetaCloudConfigNetworkingUnion` + + Network configuration policy. + + - `type BetaUnrestrictedNetwork struct{…}` + + Unrestricted network access. + + - `Type Unrestricted` + + Network policy type + + - `const UnrestrictedUnrestricted Unrestricted = "unrestricted"` + + - `type BetaLimitedNetwork struct{…}` + + Limited network access. + + - `AllowMCPServers bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `AllowPackageManagers bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `AllowedHosts []string` + + Specifies domains the container can reach. + + - `Type Limited` + + Network policy type + + - `const LimitedLimited Limited = "limited"` + + - `Packages BetaPackages` + + Package manager configuration. + + - `Apt []string` + + Ubuntu/Debian packages to install + + - `Cargo []string` + + Rust packages to install + + - `Gem []string` + + Ruby packages to install + + - `Go []string` + + Go packages to install + + - `Npm []string` + + Node.js packages to install + + - `Pip []string` + + Python packages to install + + - `Type BetaPackagesType` + + Package configuration type + + - `const BetaPackagesTypePackages BetaPackagesType = "packages"` + + - `Type Cloud` + + Environment type + + - `const CloudCloud Cloud = "cloud"` + + - `CreatedAt string` + + RFC 3339 timestamp when environment was created + + - `Description string` + + User-provided description for the environment + + - `Metadata map[string, string]` + + User-provided metadata key-value pairs + + - `Name string` + + Human-readable name for the environment + + - `Type Environment` + + The type of object (always 'environment') + + - `const EnvironmentEnvironment Environment = "environment"` + + - `UpdatedAt string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaEnvironment, err := client.Beta.Environments.Update( + context.TODO(), + "env_011CZkZ9X2dpNyB7HsEFoRfW", + anthropic.BetaEnvironmentUpdateParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaEnvironment.ID) +} +``` diff --git a/content/en/api/go/beta/files.md b/content/en/api/go/beta/files.md index 43ad241f9..5169c3bde 100644 --- a/content/en/api/go/beta/files.md +++ b/content/en/api/go/beta/files.md @@ -66,8 +66,6 @@ Upload File - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type FileMetadata struct{…}` @@ -106,6 +104,20 @@ Upload File Whether the file can be downloaded. + - `Scope BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `ID string` + + The ID of the scoping resource (e.g., the session ID). + + - `Type Session` + + The type of scope (e.g., `"session"`). + + - `const SessionSession Session = "session"` + ### Example ```go @@ -161,6 +173,10 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. + - `ScopeID param.Field[string]` + + Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `Betas param.Field[[]AnthropicBeta]` Header param: Optional header to specify the beta version(s) you want to use. @@ -211,8 +227,6 @@ List Files - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type FileMetadata struct{…}` @@ -251,6 +265,20 @@ List Files Whether the file can be downloaded. + - `Scope BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `ID string` + + The ID of the scoping resource (e.g., the session ID). + + - `Type Session` + + The type of scope (e.g., `"session"`). + + - `const SessionSession Session = "session"` + ### Example ```go @@ -344,8 +372,6 @@ Download File - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaFileDownloadResponse interface{…}` @@ -447,8 +473,6 @@ Get File Metadata - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type FileMetadata struct{…}` @@ -487,6 +511,20 @@ Get File Metadata Whether the file can be downloaded. + - `Scope BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `ID string` + + The ID of the scoping resource (e.g., the session ID). + + - `Type Session` + + The type of scope (e.g., `"session"`). + + - `const SessionSession Session = "session"` + ### Example ```go @@ -584,8 +622,6 @@ Delete File - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type DeletedFile struct{…}` @@ -635,6 +671,20 @@ func main() { ## Domain Types +### Beta File Scope + +- `type BetaFileScope struct{…}` + + - `ID string` + + The ID of the scoping resource (e.g., the session ID). + + - `Type Session` + + The type of scope (e.g., `"session"`). + + - `const SessionSession Session = "session"` + ### Deleted File - `type DeletedFile struct{…}` @@ -688,3 +738,17 @@ func main() { - `Downloadable bool` Whether the file can be downloaded. + + - `Scope BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `ID string` + + The ID of the scoping resource (e.g., the session ID). + + - `Type Session` + + The type of scope (e.g., `"session"`). + + - `const SessionSession Session = "session"` diff --git a/content/en/api/go/beta/files/delete.md b/content/en/api/go/beta/files/delete.md index fa30d0218..66e3b998e 100644 --- a/content/en/api/go/beta/files/delete.md +++ b/content/en/api/go/beta/files/delete.md @@ -64,8 +64,6 @@ Delete File - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type DeletedFile struct{…}` diff --git a/content/en/api/go/beta/files/download.md b/content/en/api/go/beta/files/download.md index bed6d1295..696f1f3f0 100644 --- a/content/en/api/go/beta/files/download.md +++ b/content/en/api/go/beta/files/download.md @@ -64,8 +64,6 @@ Download File - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaFileDownloadResponse interface{…}` diff --git a/content/en/api/go/beta/files/list.md b/content/en/api/go/beta/files/list.md index 4d5e2250e..3d9a5ec92 100644 --- a/content/en/api/go/beta/files/list.md +++ b/content/en/api/go/beta/files/list.md @@ -24,6 +24,10 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. + - `ScopeID param.Field[string]` + + Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `Betas param.Field[[]AnthropicBeta]` Header param: Optional header to specify the beta version(s) you want to use. @@ -74,8 +78,6 @@ List Files - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type FileMetadata struct{…}` @@ -114,6 +116,20 @@ List Files Whether the file can be downloaded. + - `Scope BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `ID string` + + The ID of the scoping resource (e.g., the session ID). + + - `Type Session` + + The type of scope (e.g., `"session"`). + + - `const SessionSession Session = "session"` + ### Example ```go diff --git a/content/en/api/go/beta/files/retrieve_metadata.md b/content/en/api/go/beta/files/retrieve_metadata.md index 3d71ea0a3..71a2d9021 100644 --- a/content/en/api/go/beta/files/retrieve_metadata.md +++ b/content/en/api/go/beta/files/retrieve_metadata.md @@ -64,8 +64,6 @@ Get File Metadata - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type FileMetadata struct{…}` @@ -104,6 +102,20 @@ Get File Metadata Whether the file can be downloaded. + - `Scope BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `ID string` + + The ID of the scoping resource (e.g., the session ID). + + - `Type Session` + + The type of scope (e.g., `"session"`). + + - `const SessionSession Session = "session"` + ### Example ```go diff --git a/content/en/api/go/beta/files/upload.md b/content/en/api/go/beta/files/upload.md index e7886123e..db299a53a 100644 --- a/content/en/api/go/beta/files/upload.md +++ b/content/en/api/go/beta/files/upload.md @@ -64,8 +64,6 @@ Upload File - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type FileMetadata struct{…}` @@ -104,6 +102,20 @@ Upload File Whether the file can be downloaded. + - `Scope BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `ID string` + + The ID of the scoping resource (e.g., the session ID). + + - `Type Session` + + The type of scope (e.g., `"session"`). + + - `const SessionSession Session = "session"` + ### Example ```go diff --git a/content/en/api/go/beta/messages.md b/content/en/api/go/beta/messages.md index bfaa98b05..59bcbf86b 100644 --- a/content/en/api/go/beta/messages.md +++ b/content/en/api/go/beta/messages.md @@ -4331,10 +4331,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. - - `UserProfileID param.Field[string]` - - Body param: The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `Betas param.Field[[]AnthropicBeta]` Header param: Optional header to specify the beta version(s) you want to use. @@ -4385,8 +4381,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessage struct{…}` @@ -5316,9 +5310,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -9940,8 +9938,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageTokensCount struct{…}` @@ -9984,7 +9980,7 @@ func main() { }}, Role: anthropic.BetaMessageParamRoleUser, }}, - Model: anthropic.ModelClaudeOpus4_6, + Model: anthropic.ModelClaudeMythosPreview, }) if err != nil { panic(err.Error()) @@ -17182,9 +17178,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -22522,9 +22522,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -23766,9 +23770,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -34902,9 +34910,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -36971,10 +36983,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `UserProfileID string` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `Betas param.Field[[]AnthropicBeta]` Header param: Optional header to specify the beta version(s) you want to use. @@ -37025,8 +37033,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` @@ -37226,8 +37232,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` @@ -37427,8 +37431,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` @@ -37616,8 +37618,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` @@ -37809,8 +37809,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaDeletedMessageBatch struct{…}` @@ -37928,8 +37926,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatchIndividualResponse struct{…}` @@ -38877,9 +38873,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -40475,9 +40475,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -41847,9 +41851,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -43181,9 +43189,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` diff --git a/content/en/api/go/beta/messages/batches.md b/content/en/api/go/beta/messages/batches.md index 4df802bbe..0b9c7ea1a 100644 --- a/content/en/api/go/beta/messages/batches.md +++ b/content/en/api/go/beta/messages/batches.md @@ -2619,9 +2619,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -4688,10 +4692,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `UserProfileID string` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `Betas param.Field[[]AnthropicBeta]` Header param: Optional header to specify the beta version(s) you want to use. @@ -4742,8 +4742,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` @@ -4943,8 +4941,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` @@ -5144,8 +5140,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` @@ -5333,8 +5327,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` @@ -5526,8 +5518,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaDeletedMessageBatch struct{…}` @@ -5645,8 +5635,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatchIndividualResponse struct{…}` @@ -6594,9 +6582,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -8192,9 +8184,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -9564,9 +9560,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -10898,9 +10898,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` diff --git a/content/en/api/go/beta/messages/batches/cancel.md b/content/en/api/go/beta/messages/batches/cancel.md index 2501ff86e..911a03c5b 100644 --- a/content/en/api/go/beta/messages/batches/cancel.md +++ b/content/en/api/go/beta/messages/batches/cancel.md @@ -68,8 +68,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` diff --git a/content/en/api/go/beta/messages/batches/create.md b/content/en/api/go/beta/messages/batches/create.md index f0d53bb45..abf7f6e16 100644 --- a/content/en/api/go/beta/messages/batches/create.md +++ b/content/en/api/go/beta/messages/batches/create.md @@ -2617,9 +2617,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -4686,10 +4690,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `UserProfileID string` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `Betas param.Field[[]AnthropicBeta]` Header param: Optional header to specify the beta version(s) you want to use. @@ -4740,8 +4740,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` diff --git a/content/en/api/go/beta/messages/batches/delete.md b/content/en/api/go/beta/messages/batches/delete.md index 5ed4a2d2e..7ef05abdc 100644 --- a/content/en/api/go/beta/messages/batches/delete.md +++ b/content/en/api/go/beta/messages/batches/delete.md @@ -68,8 +68,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaDeletedMessageBatch struct{…}` diff --git a/content/en/api/go/beta/messages/batches/list.md b/content/en/api/go/beta/messages/batches/list.md index 645e402a0..60fdf6abf 100644 --- a/content/en/api/go/beta/messages/batches/list.md +++ b/content/en/api/go/beta/messages/batches/list.md @@ -76,8 +76,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` diff --git a/content/en/api/go/beta/messages/batches/results.md b/content/en/api/go/beta/messages/batches/results.md index 238d86746..9036935ca 100644 --- a/content/en/api/go/beta/messages/batches/results.md +++ b/content/en/api/go/beta/messages/batches/results.md @@ -68,8 +68,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatchIndividualResponse struct{…}` @@ -1017,9 +1015,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` diff --git a/content/en/api/go/beta/messages/batches/retrieve.md b/content/en/api/go/beta/messages/batches/retrieve.md index e88f7a42d..8c3882e78 100644 --- a/content/en/api/go/beta/messages/batches/retrieve.md +++ b/content/en/api/go/beta/messages/batches/retrieve.md @@ -66,8 +66,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageBatch struct{…}` diff --git a/content/en/api/go/beta/messages/count_tokens.md b/content/en/api/go/beta/messages/count_tokens.md index c68362934..da413ab49 100644 --- a/content/en/api/go/beta/messages/count_tokens.md +++ b/content/en/api/go/beta/messages/count_tokens.md @@ -4287,8 +4287,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessageTokensCount struct{…}` @@ -4331,7 +4329,7 @@ func main() { }}, Role: anthropic.BetaMessageParamRoleUser, }}, - Model: anthropic.ModelClaudeOpus4_6, + Model: anthropic.ModelClaudeMythosPreview, }) if err != nil { panic(err.Error()) diff --git a/content/en/api/go/beta/messages/create.md b/content/en/api/go/beta/messages/create.md index e8778c7aa..07350992b 100644 --- a/content/en/api/go/beta/messages/create.md +++ b/content/en/api/go/beta/messages/create.md @@ -4329,10 +4329,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. - - `UserProfileID param.Field[string]` - - Body param: The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `Betas param.Field[[]AnthropicBeta]` Header param: Optional header to specify the beta version(s) you want to use. @@ -4383,8 +4379,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaMessage struct{…}` @@ -5314,9 +5308,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` diff --git a/content/en/api/go/beta/models.md b/content/en/api/go/beta/models.md index d8956f5a7..df8b69a8d 100644 --- a/content/en/api/go/beta/models.md +++ b/content/en/api/go/beta/models.md @@ -78,8 +78,6 @@ The Models API response can be used to determine which models are available for - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaModelInfo struct{…}` @@ -359,8 +357,6 @@ The Models API response can be used to determine information about a specific mo - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaModelInfo struct{…}` diff --git a/content/en/api/go/beta/models/list.md b/content/en/api/go/beta/models/list.md index c5a5b8051..b18b485e6 100644 --- a/content/en/api/go/beta/models/list.md +++ b/content/en/api/go/beta/models/list.md @@ -76,8 +76,6 @@ The Models API response can be used to determine which models are available for - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaModelInfo struct{…}` diff --git a/content/en/api/go/beta/models/retrieve.md b/content/en/api/go/beta/models/retrieve.md index f438e496a..37d330f85 100644 --- a/content/en/api/go/beta/models/retrieve.md +++ b/content/en/api/go/beta/models/retrieve.md @@ -66,8 +66,6 @@ The Models API response can be used to determine information about a specific mo - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaModelInfo struct{…}` diff --git a/content/en/api/go/beta/sessions.md b/content/en/api/go/beta/sessions.md new file mode 100644 index 000000000..0f30461db --- /dev/null +++ b/content/en/api/go/beta/sessions.md @@ -0,0 +1,14363 @@ +# Sessions + +## Create + +`client.Beta.Sessions.New(ctx, params) (*BetaManagedAgentsSession, error)` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `params BetaSessionNewParams` + + - `Agent param.Field[BetaSessionNewParamsAgentUnion]` + + Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `string` + + - `type BetaManagedAgentsAgentParamsResp struct{…}` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `ID string` + + The `agent` ID. + + - `Type BetaManagedAgentsAgentParamsType` + + - `const BetaManagedAgentsAgentParamsTypeAgent BetaManagedAgentsAgentParamsType = "agent"` + + - `Version int64` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + + - `EnvironmentID param.Field[string]` + + Body param: ID of the `environment` defining the container configuration for this session. + + - `Metadata param.Field[map[string, string]]` + + Body param: Arbitrary key-value metadata attached to the session. + + - `Resources param.Field[[]BetaSessionNewParamsResourceUnion]` + + Body param: Resources (e.g. repositories, files) to mount into the session's container. + + - `type BetaManagedAgentsGitHubRepositoryResourceParamsResp struct{…}` + + Mount a GitHub repository into the session's container. + + - `AuthorizationToken string` + + GitHub authorization token used to clone the repository. + + - `Type BetaManagedAgentsGitHubRepositoryResourceParamsType` + + - `const BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceParamsType = "github_repository"` + + - `URL string` + + Github URL of the repository + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceParamsCheckoutUnionResp` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `MountPath string` + + Mount path in the container. Defaults to `/workspace/`. + + - `type BetaManagedAgentsFileResourceParamsResp struct{…}` + + Mount a file uploaded via the Files API into the session. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileResourceParamsType` + + - `const BetaManagedAgentsFileResourceParamsTypeFile BetaManagedAgentsFileResourceParamsType = "file"` + + - `MountPath string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `Title param.Field[string]` + + Body param: Human-readable session title. + + - `VaultIDs param.Field[[]string]` + + Body param: Vault IDs for stored credentials the agent can use during the session. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSession, err := client.Beta.Sessions.New(context.TODO(), anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{ + OfString: anthropic.String("agent_011CZkYpogX7uDKUyvBTophP"), + }, + EnvironmentID: "env_011CZkZ9X2dpNyB7HsEFoRfW", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSession.ID) +} +``` + +## List + +`client.Beta.Sessions.List(ctx, params) (*PageCursor[BetaManagedAgentsSession], error)` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `params BetaSessionListParams` + + - `AgentID param.Field[string]` + + Query param: Filter sessions created with this agent ID. + + - `AgentVersion param.Field[int64]` + + Query param: Filter by agent version. Only applies when agent_id is also set. + + - `CreatedAtGt param.Field[Time]` + + Query param: Return sessions created after this time (exclusive). + + - `CreatedAtGte param.Field[Time]` + + Query param: Return sessions created at or after this time (inclusive). + + - `CreatedAtLt param.Field[Time]` + + Query param: Return sessions created before this time (exclusive). + + - `CreatedAtLte param.Field[Time]` + + Query param: Return sessions created at or before this time (inclusive). + + - `IncludeArchived param.Field[bool]` + + Query param: When true, includes archived sessions. Default: false (exclude archived). + + - `Limit param.Field[int64]` + + Query param: Maximum number of results to return. + + - `Order param.Field[BetaSessionListParamsOrder]` + + Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `const BetaSessionListParamsOrderAsc BetaSessionListParamsOrder = "asc"` + + - `const BetaSessionListParamsOrderDesc BetaSessionListParamsOrder = "desc"` + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Sessions.List(context.TODO(), anthropic.BetaSessionListParams{ + + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Sessions.Get(ctx, sessionID, query) (*BetaManagedAgentsSession, error)` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `sessionID string` + +- `query BetaSessionGetParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSession, err := client.Beta.Sessions.Get( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionGetParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSession.ID) +} +``` + +## Update + +`client.Beta.Sessions.Update(ctx, sessionID, params) (*BetaManagedAgentsSession, error)` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `sessionID string` + +- `params BetaSessionUpdateParams` + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + + - `Title param.Field[string]` + + Body param: Human-readable session title. + + - `VaultIDs param.Field[[]string]` + + Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSession, err := client.Beta.Sessions.Update( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionUpdateParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSession.ID) +} +``` + +## Delete + +`client.Beta.Sessions.Delete(ctx, sessionID, body) (*BetaManagedAgentsDeletedSession, error)` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `sessionID string` + +- `body BetaSessionDeleteParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeletedSession struct{…}` + + Confirmation that a `session` has been permanently deleted. + + - `ID string` + + - `Type BetaManagedAgentsDeletedSessionType` + + - `const BetaManagedAgentsDeletedSessionTypeSessionDeleted BetaManagedAgentsDeletedSessionType = "session_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeletedSession, err := client.Beta.Sessions.Delete( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionDeleteParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeletedSession.ID) +} +``` + +## Archive + +`client.Beta.Sessions.Archive(ctx, sessionID, body) (*BetaManagedAgentsSession, error)` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `sessionID string` + +- `body BetaSessionArchiveParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSession, err := client.Beta.Sessions.Archive( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionArchiveParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSession.ID) +} +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `type BetaManagedAgentsAgentParamsResp struct{…}` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `ID string` + + The `agent` ID. + + - `Type BetaManagedAgentsAgentParamsType` + + - `const BetaManagedAgentsAgentParamsTypeAgent BetaManagedAgentsAgentParamsType = "agent"` + + - `Version int64` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + +### Beta Managed Agents Cache Creation Usage + +- `type BetaManagedAgentsCacheCreationUsage struct{…}` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + +### Beta Managed Agents Deleted Session + +- `type BetaManagedAgentsDeletedSession struct{…}` + + Confirmation that a `session` has been permanently deleted. + + - `ID string` + + - `Type BetaManagedAgentsDeletedSessionType` + + - `const BetaManagedAgentsDeletedSessionTypeSessionDeleted BetaManagedAgentsDeletedSessionType = "session_deleted"` + +### Beta Managed Agents File Resource Params + +- `type BetaManagedAgentsFileResourceParamsResp struct{…}` + + Mount a file uploaded via the Files API into the session. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileResourceParamsType` + + - `const BetaManagedAgentsFileResourceParamsTypeFile BetaManagedAgentsFileResourceParamsType = "file"` + + - `MountPath string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `type BetaManagedAgentsGitHubRepositoryResourceParamsResp struct{…}` + + Mount a GitHub repository into the session's container. + + - `AuthorizationToken string` + + GitHub authorization token used to clone the repository. + + - `Type BetaManagedAgentsGitHubRepositoryResourceParamsType` + + - `const BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceParamsType = "github_repository"` + + - `URL string` + + Github URL of the repository + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceParamsCheckoutUnionResp` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `MountPath string` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `type BetaManagedAgentsSessionAgent struct{…}` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + +### Beta Managed Agents Session Stats + +- `type BetaManagedAgentsSessionStats struct{…}` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `type BetaManagedAgentsSessionUsage struct{…}` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + +# Events + +## List + +`client.Beta.Sessions.Events.List(ctx, sessionID, params) (*PageCursor[BetaManagedAgentsSessionEventUnion], error)` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `sessionID string` + +- `params BetaSessionEventListParams` + + - `Limit param.Field[int64]` + + Query param: Query parameter for limit + + - `Order param.Field[BetaSessionEventListParamsOrder]` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `const BetaSessionEventListParamsOrderAsc BetaSessionEventListParamsOrder = "asc"` + + - `const BetaSessionEventListParamsOrderDesc BetaSessionEventListParamsOrder = "desc"` + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSessionEventUnion interface{…}` + + Union type for all event types in a session. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Sessions.Events.List( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionEventListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Send + +`client.Beta.Sessions.Events.Send(ctx, sessionID, params) (*BetaManagedAgentsSendSessionEvents, error)` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `sessionID string` + +- `params BetaSessionEventSendParams` + + - `Events param.Field[[]BetaManagedAgentsEventParamsUnionResp]` + + Body param: Events to send to the `session`. + + - `type BetaManagedAgentsUserMessageEventParamsResp struct{…}` + + Parameters for sending a user message to the session. + + - `Content []BetaManagedAgentsUserMessageEventParamsContentUnionResp` + + Array of content blocks for the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventParamsType` + + - `const BetaManagedAgentsUserMessageEventParamsTypeUserMessage BetaManagedAgentsUserMessageEventParamsType = "user.message"` + + - `type BetaManagedAgentsUserInterruptEventParamsResp struct{…}` + + Parameters for sending an interrupt to pause the agent. + + - `Type BetaManagedAgentsUserInterruptEventParamsType` + + - `const BetaManagedAgentsUserInterruptEventParamsTypeUserInterrupt BetaManagedAgentsUserInterruptEventParamsType = "user.interrupt"` + + - `type BetaManagedAgentsUserToolConfirmationEventParamsResp struct{…}` + + Parameters for confirming or denying a tool execution request. + + - `Result BetaManagedAgentsUserToolConfirmationEventParamsResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultAllow BetaManagedAgentsUserToolConfirmationEventParamsResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultDeny BetaManagedAgentsUserToolConfirmationEventParamsResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventParamsType` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventParamsType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `type BetaManagedAgentsUserCustomToolResultEventParamsResp struct{…}` + + Parameters for providing the result of a custom tool execution. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventParamsType` + + - `const BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventParamsType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventParamsContentUnionResp` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSendSessionEvents struct{…}` + + Events that were successfully sent to the session. + + - `Data []BetaManagedAgentsSendSessionEventsDataUnion` + + Sent events + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSendSessionEvents, err := client.Beta.Sessions.Events.Send( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionEventSendParams{ + Events: []anthropic.BetaManagedAgentsEventParamsUnion{anthropic.BetaManagedAgentsEventParamsUnion{ + OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{ + Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{ + OfText: &anthropic.BetaManagedAgentsTextBlockParam{ + Text: "Where is my order #1234?", + Type: anthropic.BetaManagedAgentsTextBlockTypeText, + }, + }}, + Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage, + }, + }}, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSendSessionEvents.Data) +} +``` + +## Stream + +`client.Beta.Sessions.Events.Stream(ctx, sessionID, query) (*BetaManagedAgentsStreamSessionEventsUnion, error)` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `sessionID string` + +- `query BetaSessionEventStreamParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsStreamSessionEventsUnion interface{…}` + + Server-sent event in the session stream. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + stream := client.Beta.Sessions.Events.StreamEvents( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionEventStreamParams{ + + }, + ) + for stream.Next() { + fmt.Printf("%+v\n", stream.Current()) + } + err := stream.Err() + if err != nil { + panic(err.Error()) + } +} +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + +### Beta Managed Agents Agent Message Event + +- `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + +### Beta Managed Agents Base64 Document Source + +- `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + +### Beta Managed Agents Base64 Image Source + +- `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + +### Beta Managed Agents Billing Error + +- `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + +### Beta Managed Agents Document Block + +- `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + +### Beta Managed Agents Event Params + +- `type BetaManagedAgentsEventParamsUnionResp interface{…}` + + Union type for event parameters that can be sent to a session. + + - `type BetaManagedAgentsUserMessageEventParamsResp struct{…}` + + Parameters for sending a user message to the session. + + - `Content []BetaManagedAgentsUserMessageEventParamsContentUnionResp` + + Array of content blocks for the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventParamsType` + + - `const BetaManagedAgentsUserMessageEventParamsTypeUserMessage BetaManagedAgentsUserMessageEventParamsType = "user.message"` + + - `type BetaManagedAgentsUserInterruptEventParamsResp struct{…}` + + Parameters for sending an interrupt to pause the agent. + + - `Type BetaManagedAgentsUserInterruptEventParamsType` + + - `const BetaManagedAgentsUserInterruptEventParamsTypeUserInterrupt BetaManagedAgentsUserInterruptEventParamsType = "user.interrupt"` + + - `type BetaManagedAgentsUserToolConfirmationEventParamsResp struct{…}` + + Parameters for confirming or denying a tool execution request. + + - `Result BetaManagedAgentsUserToolConfirmationEventParamsResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultAllow BetaManagedAgentsUserToolConfirmationEventParamsResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultDeny BetaManagedAgentsUserToolConfirmationEventParamsResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventParamsType` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventParamsType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `type BetaManagedAgentsUserCustomToolResultEventParamsResp struct{…}` + + Parameters for providing the result of a custom tool execution. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventParamsType` + + - `const BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventParamsType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventParamsContentUnionResp` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + +### Beta Managed Agents File Image Source + +- `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + +### Beta Managed Agents Image Block + +- `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + +### Beta Managed Agents Retry Status Exhausted + +- `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + +### Beta Managed Agents Send Session Events + +- `type BetaManagedAgentsSendSessionEvents struct{…}` + + Events that were successfully sent to the session. + + - `Data []BetaManagedAgentsSendSessionEventsDataUnion` + + Sent events + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Beta Managed Agents Session End Turn + +- `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + +### Beta Managed Agents Session Error Event + +- `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + +### Beta Managed Agents Session Event + +- `type BetaManagedAgentsSessionEventUnion interface{…}` + + Union type for all event types in a session. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `type BetaManagedAgentsSpanModelUsage struct{…}` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + +### Beta Managed Agents Stream Session Events + +- `type BetaManagedAgentsStreamSessionEventsUnion interface{…}` + + Server-sent event in the session stream. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Beta Managed Agents Text Block + +- `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + +### Beta Managed Agents Unknown Error + +- `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + +### Beta Managed Agents URL Document Source + +- `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `type BetaManagedAgentsUserCustomToolResultEventParamsResp struct{…}` + + Parameters for providing the result of a custom tool execution. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventParamsType` + + - `const BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventParamsType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventParamsContentUnionResp` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `type BetaManagedAgentsUserInterruptEventParamsResp struct{…}` + + Parameters for sending an interrupt to pause the agent. + + - `Type BetaManagedAgentsUserInterruptEventParamsType` + + - `const BetaManagedAgentsUserInterruptEventParamsTypeUserInterrupt BetaManagedAgentsUserInterruptEventParamsType = "user.interrupt"` + +### Beta Managed Agents User Message Event + +- `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `type BetaManagedAgentsUserMessageEventParamsResp struct{…}` + + Parameters for sending a user message to the session. + + - `Content []BetaManagedAgentsUserMessageEventParamsContentUnionResp` + + Array of content blocks for the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventParamsType` + + - `const BetaManagedAgentsUserMessageEventParamsTypeUserMessage BetaManagedAgentsUserMessageEventParamsType = "user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `type BetaManagedAgentsUserToolConfirmationEventParamsResp struct{…}` + + Parameters for confirming or denying a tool execution request. + + - `Result BetaManagedAgentsUserToolConfirmationEventParamsResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultAllow BetaManagedAgentsUserToolConfirmationEventParamsResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultDeny BetaManagedAgentsUserToolConfirmationEventParamsResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventParamsType` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventParamsType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`client.Beta.Sessions.Resources.Add(ctx, sessionID, params) (*BetaManagedAgentsFileResource, error)` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `sessionID string` + +- `params BetaSessionResourceAddParams` + + - `BetaManagedAgentsFileResourceParams param.Field[BetaManagedAgentsFileResourceParamsResp]` + + Body param: Mount a file uploaded via the Files API into the session. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsFileResource, err := client.Beta.Sessions.Resources.Add( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionResourceAddParams{ + BetaManagedAgentsFileResourceParams: anthropic.BetaManagedAgentsFileResourceParams{ + FileID: "file_011CNha8iCJcU1wXNR6q4V8w", + Type: anthropic.BetaManagedAgentsFileResourceParamsTypeFile, + }, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsFileResource.ID) +} +``` + +## List + +`client.Beta.Sessions.Resources.List(ctx, sessionID, params) (*PageCursor[BetaManagedAgentsSessionResourceUnion], error)` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `sessionID string` + +- `params BetaSessionResourceListParams` + + - `Limit param.Field[int64]` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `Page param.Field[string]` + + Query param: Opaque cursor from a previous response's next_page field. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSessionResourceUnion interface{…}` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Sessions.Resources.List( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionResourceListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Sessions.Resources.Get(ctx, resourceID, params) (*BetaSessionResourceGetResponseUnion, error)` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `resourceID string` + +- `params BetaSessionResourceGetParams` + + - `SessionID param.Field[string]` + + Path param: Path parameter session_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaSessionResourceGetResponseUnion interface{…}` + + The requested session resource. + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + resource, err := client.Beta.Sessions.Resources.Get( + context.TODO(), + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + anthropic.BetaSessionResourceGetParams{ + SessionID: "sesn_011CZkZAtmR3yMPDzynEDxu7", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", resource) +} +``` + +## Update + +`client.Beta.Sessions.Resources.Update(ctx, resourceID, params) (*BetaSessionResourceUpdateResponseUnion, error)` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `resourceID string` + +- `params BetaSessionResourceUpdateParams` + + - `SessionID param.Field[string]` + + Path param: Path parameter session_id + + - `AuthorizationToken param.Field[string]` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaSessionResourceUpdateResponseUnion interface{…}` + + The updated session resource. + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + resource, err := client.Beta.Sessions.Resources.Update( + context.TODO(), + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + anthropic.BetaSessionResourceUpdateParams{ + SessionID: "sesn_011CZkZAtmR3yMPDzynEDxu7", + AuthorizationToken: "ghp_exampletoken", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", resource) +} +``` + +## Delete + +`client.Beta.Sessions.Resources.Delete(ctx, resourceID, params) (*BetaManagedAgentsDeleteSessionResource, error)` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `resourceID string` + +- `params BetaSessionResourceDeleteParams` + + - `SessionID param.Field[string]` + + Path param: Path parameter session_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeleteSessionResource struct{…}` + + Confirmation of resource deletion. + + - `ID string` + + - `Type BetaManagedAgentsDeleteSessionResourceType` + + - `const BetaManagedAgentsDeleteSessionResourceTypeSessionResourceDeleted BetaManagedAgentsDeleteSessionResourceType = "session_resource_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeleteSessionResource, err := client.Beta.Sessions.Resources.Delete( + context.TODO(), + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + anthropic.BetaSessionResourceDeleteParams{ + SessionID: "sesn_011CZkZAtmR3yMPDzynEDxu7", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeleteSessionResource.ID) +} +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `type BetaManagedAgentsDeleteSessionResource struct{…}` + + Confirmation of resource deletion. + + - `ID string` + + - `Type BetaManagedAgentsDeleteSessionResourceType` + + - `const BetaManagedAgentsDeleteSessionResourceTypeSessionResourceDeleted BetaManagedAgentsDeleteSessionResourceType = "session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + +### Beta Managed Agents Session Resource + +- `type BetaManagedAgentsSessionResourceUnion interface{…}` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format diff --git a/content/en/api/go/beta/sessions/archive.md b/content/en/api/go/beta/sessions/archive.md new file mode 100644 index 000000000..3b308877a --- /dev/null +++ b/content/en/api/go/beta/sessions/archive.md @@ -0,0 +1,524 @@ +## Archive + +`client.Beta.Sessions.Archive(ctx, sessionID, body) (*BetaManagedAgentsSession, error)` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `sessionID string` + +- `body BetaSessionArchiveParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSession, err := client.Beta.Sessions.Archive( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionArchiveParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSession.ID) +} +``` diff --git a/content/en/api/go/beta/sessions/create.md b/content/en/api/go/beta/sessions/create.md new file mode 100644 index 000000000..5ad2df8ec --- /dev/null +++ b/content/en/api/go/beta/sessions/create.md @@ -0,0 +1,623 @@ +## Create + +`client.Beta.Sessions.New(ctx, params) (*BetaManagedAgentsSession, error)` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `params BetaSessionNewParams` + + - `Agent param.Field[BetaSessionNewParamsAgentUnion]` + + Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `string` + + - `type BetaManagedAgentsAgentParamsResp struct{…}` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `ID string` + + The `agent` ID. + + - `Type BetaManagedAgentsAgentParamsType` + + - `const BetaManagedAgentsAgentParamsTypeAgent BetaManagedAgentsAgentParamsType = "agent"` + + - `Version int64` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + + - `EnvironmentID param.Field[string]` + + Body param: ID of the `environment` defining the container configuration for this session. + + - `Metadata param.Field[map[string, string]]` + + Body param: Arbitrary key-value metadata attached to the session. + + - `Resources param.Field[[]BetaSessionNewParamsResourceUnion]` + + Body param: Resources (e.g. repositories, files) to mount into the session's container. + + - `type BetaManagedAgentsGitHubRepositoryResourceParamsResp struct{…}` + + Mount a GitHub repository into the session's container. + + - `AuthorizationToken string` + + GitHub authorization token used to clone the repository. + + - `Type BetaManagedAgentsGitHubRepositoryResourceParamsType` + + - `const BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceParamsType = "github_repository"` + + - `URL string` + + Github URL of the repository + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceParamsCheckoutUnionResp` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `MountPath string` + + Mount path in the container. Defaults to `/workspace/`. + + - `type BetaManagedAgentsFileResourceParamsResp struct{…}` + + Mount a file uploaded via the Files API into the session. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileResourceParamsType` + + - `const BetaManagedAgentsFileResourceParamsTypeFile BetaManagedAgentsFileResourceParamsType = "file"` + + - `MountPath string` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `Title param.Field[string]` + + Body param: Human-readable session title. + + - `VaultIDs param.Field[[]string]` + + Body param: Vault IDs for stored credentials the agent can use during the session. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSession, err := client.Beta.Sessions.New(context.TODO(), anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{ + OfString: anthropic.String("agent_011CZkYpogX7uDKUyvBTophP"), + }, + EnvironmentID: "env_011CZkZ9X2dpNyB7HsEFoRfW", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSession.ID) +} +``` diff --git a/content/en/api/go/beta/sessions/delete.md b/content/en/api/go/beta/sessions/delete.md new file mode 100644 index 000000000..d56e0fce3 --- /dev/null +++ b/content/en/api/go/beta/sessions/delete.md @@ -0,0 +1,106 @@ +## Delete + +`client.Beta.Sessions.Delete(ctx, sessionID, body) (*BetaManagedAgentsDeletedSession, error)` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `sessionID string` + +- `body BetaSessionDeleteParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeletedSession struct{…}` + + Confirmation that a `session` has been permanently deleted. + + - `ID string` + + - `Type BetaManagedAgentsDeletedSessionType` + + - `const BetaManagedAgentsDeletedSessionTypeSessionDeleted BetaManagedAgentsDeletedSessionType = "session_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeletedSession, err := client.Beta.Sessions.Delete( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionDeleteParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeletedSession.ID) +} +``` diff --git a/content/en/api/go/beta/sessions/events.md b/content/en/api/go/beta/sessions/events.md new file mode 100644 index 000000000..59ec09a54 --- /dev/null +++ b/content/en/api/go/beta/sessions/events.md @@ -0,0 +1,9699 @@ +# Events + +## List + +`client.Beta.Sessions.Events.List(ctx, sessionID, params) (*PageCursor[BetaManagedAgentsSessionEventUnion], error)` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `sessionID string` + +- `params BetaSessionEventListParams` + + - `Limit param.Field[int64]` + + Query param: Query parameter for limit + + - `Order param.Field[BetaSessionEventListParamsOrder]` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `const BetaSessionEventListParamsOrderAsc BetaSessionEventListParamsOrder = "asc"` + + - `const BetaSessionEventListParamsOrderDesc BetaSessionEventListParamsOrder = "desc"` + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSessionEventUnion interface{…}` + + Union type for all event types in a session. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Sessions.Events.List( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionEventListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Send + +`client.Beta.Sessions.Events.Send(ctx, sessionID, params) (*BetaManagedAgentsSendSessionEvents, error)` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `sessionID string` + +- `params BetaSessionEventSendParams` + + - `Events param.Field[[]BetaManagedAgentsEventParamsUnionResp]` + + Body param: Events to send to the `session`. + + - `type BetaManagedAgentsUserMessageEventParamsResp struct{…}` + + Parameters for sending a user message to the session. + + - `Content []BetaManagedAgentsUserMessageEventParamsContentUnionResp` + + Array of content blocks for the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventParamsType` + + - `const BetaManagedAgentsUserMessageEventParamsTypeUserMessage BetaManagedAgentsUserMessageEventParamsType = "user.message"` + + - `type BetaManagedAgentsUserInterruptEventParamsResp struct{…}` + + Parameters for sending an interrupt to pause the agent. + + - `Type BetaManagedAgentsUserInterruptEventParamsType` + + - `const BetaManagedAgentsUserInterruptEventParamsTypeUserInterrupt BetaManagedAgentsUserInterruptEventParamsType = "user.interrupt"` + + - `type BetaManagedAgentsUserToolConfirmationEventParamsResp struct{…}` + + Parameters for confirming or denying a tool execution request. + + - `Result BetaManagedAgentsUserToolConfirmationEventParamsResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultAllow BetaManagedAgentsUserToolConfirmationEventParamsResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultDeny BetaManagedAgentsUserToolConfirmationEventParamsResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventParamsType` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventParamsType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `type BetaManagedAgentsUserCustomToolResultEventParamsResp struct{…}` + + Parameters for providing the result of a custom tool execution. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventParamsType` + + - `const BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventParamsType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventParamsContentUnionResp` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSendSessionEvents struct{…}` + + Events that were successfully sent to the session. + + - `Data []BetaManagedAgentsSendSessionEventsDataUnion` + + Sent events + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSendSessionEvents, err := client.Beta.Sessions.Events.Send( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionEventSendParams{ + Events: []anthropic.BetaManagedAgentsEventParamsUnion{anthropic.BetaManagedAgentsEventParamsUnion{ + OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{ + Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{ + OfText: &anthropic.BetaManagedAgentsTextBlockParam{ + Text: "Where is my order #1234?", + Type: anthropic.BetaManagedAgentsTextBlockTypeText, + }, + }}, + Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage, + }, + }}, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSendSessionEvents.Data) +} +``` + +## Stream + +`client.Beta.Sessions.Events.Stream(ctx, sessionID, query) (*BetaManagedAgentsStreamSessionEventsUnion, error)` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `sessionID string` + +- `query BetaSessionEventStreamParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsStreamSessionEventsUnion interface{…}` + + Server-sent event in the session stream. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + stream := client.Beta.Sessions.Events.StreamEvents( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionEventStreamParams{ + + }, + ) + for stream.Next() { + fmt.Printf("%+v\n", stream.Current()) + } + err := stream.Err() + if err != nil { + panic(err.Error()) + } +} +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + +### Beta Managed Agents Agent Message Event + +- `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + +### Beta Managed Agents Base64 Document Source + +- `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + +### Beta Managed Agents Base64 Image Source + +- `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + +### Beta Managed Agents Billing Error + +- `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + +### Beta Managed Agents Document Block + +- `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + +### Beta Managed Agents Event Params + +- `type BetaManagedAgentsEventParamsUnionResp interface{…}` + + Union type for event parameters that can be sent to a session. + + - `type BetaManagedAgentsUserMessageEventParamsResp struct{…}` + + Parameters for sending a user message to the session. + + - `Content []BetaManagedAgentsUserMessageEventParamsContentUnionResp` + + Array of content blocks for the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventParamsType` + + - `const BetaManagedAgentsUserMessageEventParamsTypeUserMessage BetaManagedAgentsUserMessageEventParamsType = "user.message"` + + - `type BetaManagedAgentsUserInterruptEventParamsResp struct{…}` + + Parameters for sending an interrupt to pause the agent. + + - `Type BetaManagedAgentsUserInterruptEventParamsType` + + - `const BetaManagedAgentsUserInterruptEventParamsTypeUserInterrupt BetaManagedAgentsUserInterruptEventParamsType = "user.interrupt"` + + - `type BetaManagedAgentsUserToolConfirmationEventParamsResp struct{…}` + + Parameters for confirming or denying a tool execution request. + + - `Result BetaManagedAgentsUserToolConfirmationEventParamsResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultAllow BetaManagedAgentsUserToolConfirmationEventParamsResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultDeny BetaManagedAgentsUserToolConfirmationEventParamsResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventParamsType` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventParamsType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `type BetaManagedAgentsUserCustomToolResultEventParamsResp struct{…}` + + Parameters for providing the result of a custom tool execution. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventParamsType` + + - `const BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventParamsType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventParamsContentUnionResp` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + +### Beta Managed Agents File Image Source + +- `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + +### Beta Managed Agents Image Block + +- `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + +### Beta Managed Agents Retry Status Exhausted + +- `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + +### Beta Managed Agents Send Session Events + +- `type BetaManagedAgentsSendSessionEvents struct{…}` + + Events that were successfully sent to the session. + + - `Data []BetaManagedAgentsSendSessionEventsDataUnion` + + Sent events + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Beta Managed Agents Session End Turn + +- `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + +### Beta Managed Agents Session Error Event + +- `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + +### Beta Managed Agents Session Event + +- `type BetaManagedAgentsSessionEventUnion interface{…}` + + Union type for all event types in a session. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `type BetaManagedAgentsSpanModelUsage struct{…}` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + +### Beta Managed Agents Stream Session Events + +- `type BetaManagedAgentsStreamSessionEventsUnion interface{…}` + + Server-sent event in the session stream. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Beta Managed Agents Text Block + +- `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + +### Beta Managed Agents Unknown Error + +- `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + +### Beta Managed Agents URL Document Source + +- `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `type BetaManagedAgentsUserCustomToolResultEventParamsResp struct{…}` + + Parameters for providing the result of a custom tool execution. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventParamsType` + + - `const BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventParamsType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventParamsContentUnionResp` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `type BetaManagedAgentsUserInterruptEventParamsResp struct{…}` + + Parameters for sending an interrupt to pause the agent. + + - `Type BetaManagedAgentsUserInterruptEventParamsType` + + - `const BetaManagedAgentsUserInterruptEventParamsTypeUserInterrupt BetaManagedAgentsUserInterruptEventParamsType = "user.interrupt"` + +### Beta Managed Agents User Message Event + +- `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `type BetaManagedAgentsUserMessageEventParamsResp struct{…}` + + Parameters for sending a user message to the session. + + - `Content []BetaManagedAgentsUserMessageEventParamsContentUnionResp` + + Array of content blocks for the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventParamsType` + + - `const BetaManagedAgentsUserMessageEventParamsTypeUserMessage BetaManagedAgentsUserMessageEventParamsType = "user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `type BetaManagedAgentsUserToolConfirmationEventParamsResp struct{…}` + + Parameters for confirming or denying a tool execution request. + + - `Result BetaManagedAgentsUserToolConfirmationEventParamsResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultAllow BetaManagedAgentsUserToolConfirmationEventParamsResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultDeny BetaManagedAgentsUserToolConfirmationEventParamsResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventParamsType` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventParamsType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. diff --git a/content/en/api/go/beta/sessions/events/list.md b/content/en/api/go/beta/sessions/events/list.md new file mode 100644 index 000000000..22dae4ded --- /dev/null +++ b/content/en/api/go/beta/sessions/events/list.md @@ -0,0 +1,1480 @@ +## List + +`client.Beta.Sessions.Events.List(ctx, sessionID, params) (*PageCursor[BetaManagedAgentsSessionEventUnion], error)` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `sessionID string` + +- `params BetaSessionEventListParams` + + - `Limit param.Field[int64]` + + Query param: Query parameter for limit + + - `Order param.Field[BetaSessionEventListParamsOrder]` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `const BetaSessionEventListParamsOrderAsc BetaSessionEventListParamsOrder = "asc"` + + - `const BetaSessionEventListParamsOrderDesc BetaSessionEventListParamsOrder = "desc"` + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSessionEventUnion interface{…}` + + Union type for all event types in a session. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Sessions.Events.List( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionEventListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` diff --git a/content/en/api/go/beta/sessions/events/send.md b/content/en/api/go/beta/sessions/events/send.md new file mode 100644 index 000000000..f55c562fc --- /dev/null +++ b/content/en/api/go/beta/sessions/events/send.md @@ -0,0 +1,846 @@ +## Send + +`client.Beta.Sessions.Events.Send(ctx, sessionID, params) (*BetaManagedAgentsSendSessionEvents, error)` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `sessionID string` + +- `params BetaSessionEventSendParams` + + - `Events param.Field[[]BetaManagedAgentsEventParamsUnionResp]` + + Body param: Events to send to the `session`. + + - `type BetaManagedAgentsUserMessageEventParamsResp struct{…}` + + Parameters for sending a user message to the session. + + - `Content []BetaManagedAgentsUserMessageEventParamsContentUnionResp` + + Array of content blocks for the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventParamsType` + + - `const BetaManagedAgentsUserMessageEventParamsTypeUserMessage BetaManagedAgentsUserMessageEventParamsType = "user.message"` + + - `type BetaManagedAgentsUserInterruptEventParamsResp struct{…}` + + Parameters for sending an interrupt to pause the agent. + + - `Type BetaManagedAgentsUserInterruptEventParamsType` + + - `const BetaManagedAgentsUserInterruptEventParamsTypeUserInterrupt BetaManagedAgentsUserInterruptEventParamsType = "user.interrupt"` + + - `type BetaManagedAgentsUserToolConfirmationEventParamsResp struct{…}` + + Parameters for confirming or denying a tool execution request. + + - `Result BetaManagedAgentsUserToolConfirmationEventParamsResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultAllow BetaManagedAgentsUserToolConfirmationEventParamsResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsResultDeny BetaManagedAgentsUserToolConfirmationEventParamsResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventParamsType` + + - `const BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventParamsType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `type BetaManagedAgentsUserCustomToolResultEventParamsResp struct{…}` + + Parameters for providing the result of a custom tool execution. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventParamsType` + + - `const BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventParamsType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventParamsContentUnionResp` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSendSessionEvents struct{…}` + + Events that were successfully sent to the session. + + - `Data []BetaManagedAgentsSendSessionEventsDataUnion` + + Sent events + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSendSessionEvents, err := client.Beta.Sessions.Events.Send( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionEventSendParams{ + Events: []anthropic.BetaManagedAgentsEventParamsUnion{anthropic.BetaManagedAgentsEventParamsUnion{ + OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{ + Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{ + OfText: &anthropic.BetaManagedAgentsTextBlockParam{ + Text: "Where is my order #1234?", + Type: anthropic.BetaManagedAgentsTextBlockTypeText, + }, + }}, + Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage, + }, + }}, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSendSessionEvents.Data) +} +``` diff --git a/content/en/api/go/beta/sessions/events/stream.md b/content/en/api/go/beta/sessions/events/stream.md new file mode 100644 index 000000000..1a62060a2 --- /dev/null +++ b/content/en/api/go/beta/sessions/events/stream.md @@ -0,0 +1,1467 @@ +## Stream + +`client.Beta.Sessions.Events.Stream(ctx, sessionID, query) (*BetaManagedAgentsStreamSessionEventsUnion, error)` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `sessionID string` + +- `query BetaSessionEventStreamParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsStreamSessionEventsUnion interface{…}` + + Server-sent event in the session stream. + + - `type BetaManagedAgentsUserMessageEvent struct{…}` + + A user message event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsUserMessageEventContentUnion` + + Array of content blocks comprising the user message. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `Type BetaManagedAgentsUserMessageEventType` + + - `const BetaManagedAgentsUserMessageEventTypeUserMessage BetaManagedAgentsUserMessageEventType = "user.message"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserInterruptEvent struct{…}` + + An interrupt event that pauses agent execution and returns control to the user. + + - `ID string` + + Unique identifier for this event. + + - `Type BetaManagedAgentsUserInterruptEventType` + + - `const BetaManagedAgentsUserInterruptEventTypeUserInterrupt BetaManagedAgentsUserInterruptEventType = "user.interrupt"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserToolConfirmationEvent struct{…}` + + A tool confirmation event that approves or denies a pending tool execution. + + - `ID string` + + Unique identifier for this event. + + - `Result BetaManagedAgentsUserToolConfirmationEventResult` + + UserToolConfirmationResult enum + + - `const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"` + + - `const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"` + + - `ToolUseID string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserToolConfirmationEventType` + + - `const BetaManagedAgentsUserToolConfirmationEventTypeUserToolConfirmation BetaManagedAgentsUserToolConfirmationEventType = "user.tool_confirmation"` + + - `DenyMessage string` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsUserCustomToolResultEvent struct{…}` + + Event sent by the client providing the result of a custom tool execution. + + - `ID string` + + Unique identifier for this event. + + - `CustomToolUseID string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type BetaManagedAgentsUserCustomToolResultEventType` + + - `const BetaManagedAgentsUserCustomToolResultEventTypeUserCustomToolResult BetaManagedAgentsUserCustomToolResultEventType = "user.custom_tool_result"` + + - `Content []BetaManagedAgentsUserCustomToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `type BetaManagedAgentsAgentCustomToolUseEvent struct{…}` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the custom tool being called. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentCustomToolUseEventType` + + - `const BetaManagedAgentsAgentCustomToolUseEventTypeAgentCustomToolUse BetaManagedAgentsAgentCustomToolUseEventType = "agent.custom_tool_use"` + + - `type BetaManagedAgentsAgentMessageEvent struct{…}` + + An agent response event in the session conversation. + + - `ID string` + + Unique identifier for this event. + + - `Content []BetaManagedAgentsTextBlock` + + Array of text blocks comprising the agent response. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMessageEventType` + + - `const BetaManagedAgentsAgentMessageEventTypeAgentMessage BetaManagedAgentsAgentMessageEventType = "agent.message"` + + - `type BetaManagedAgentsAgentThinkingEvent struct{…}` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThinkingEventType` + + - `const BetaManagedAgentsAgentThinkingEventTypeAgentThinking BetaManagedAgentsAgentThinkingEventType = "agent.thinking"` + + - `type BetaManagedAgentsAgentMCPToolUseEvent struct{…}` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `MCPServerName string` + + Name of the MCP server providing the tool. + + - `Name string` + + Name of the MCP tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolUseEventType` + + - `const BetaManagedAgentsAgentMCPToolUseEventTypeAgentMCPToolUse BetaManagedAgentsAgentMCPToolUseEventType = "agent.mcp_tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentMCPToolResultEvent struct{…}` + + Event representing the result of an MCP tool execution. + + - `ID string` + + Unique identifier for this event. + + - `MCPToolUseID string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentMCPToolResultEventType` + + - `const BetaManagedAgentsAgentMCPToolResultEventTypeAgentMCPToolResult BetaManagedAgentsAgentMCPToolResultEventType = "agent.mcp_tool_result"` + + - `Content []BetaManagedAgentsAgentMCPToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentToolUseEvent struct{…}` + + Event emitted when the agent invokes a built-in agent tool. + + - `ID string` + + Unique identifier for this event. + + - `Input map[string, any]` + + Input parameters for the tool call. + + - `Name string` + + Name of the agent tool being used. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentToolUseEventType` + + - `const BetaManagedAgentsAgentToolUseEventTypeAgentToolUse BetaManagedAgentsAgentToolUseEventType = "agent.tool_use"` + + - `EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission` + + AgentEvaluatedPermission enum + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"` + + - `const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"` + + - `type BetaManagedAgentsAgentToolResultEvent struct{…}` + + Event representing the result of an agent tool execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `ToolUseID string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type BetaManagedAgentsAgentToolResultEventType` + + - `const BetaManagedAgentsAgentToolResultEventTypeAgentToolResult BetaManagedAgentsAgentToolResultEventType = "agent.tool_result"` + + - `Content []BetaManagedAgentsAgentToolResultEventContentUnion` + + The result content returned by the tool. + + - `type BetaManagedAgentsTextBlock struct{…}` + + Regular text content. + + - `Text string` + + The text content. + + - `Type BetaManagedAgentsTextBlockType` + + - `const BetaManagedAgentsTextBlockTypeText BetaManagedAgentsTextBlockType = "text"` + + - `type BetaManagedAgentsImageBlock struct{…}` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source BetaManagedAgentsImageBlockSourceUnion` + + Union type for image source variants. + + - `type BetaManagedAgentsBase64ImageSource struct{…}` + + Base64-encoded image data. + + - `Data string` + + Base64-encoded image data. + + - `MediaType string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type BetaManagedAgentsBase64ImageSourceType` + + - `const BetaManagedAgentsBase64ImageSourceTypeBase64 BetaManagedAgentsBase64ImageSourceType = "base64"` + + - `type BetaManagedAgentsURLImageSource struct{…}` + + Image referenced by URL. + + - `Type BetaManagedAgentsURLImageSourceType` + + - `const BetaManagedAgentsURLImageSourceTypeURL BetaManagedAgentsURLImageSourceType = "url"` + + - `URL string` + + URL of the image to fetch. + + - `type BetaManagedAgentsFileImageSource struct{…}` + + Image referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileImageSourceType` + + - `const BetaManagedAgentsFileImageSourceTypeFile BetaManagedAgentsFileImageSourceType = "file"` + + - `Type BetaManagedAgentsImageBlockType` + + - `const BetaManagedAgentsImageBlockTypeImage BetaManagedAgentsImageBlockType = "image"` + + - `type BetaManagedAgentsDocumentBlock struct{…}` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source BetaManagedAgentsDocumentBlockSourceUnion` + + Union type for document source variants. + + - `type BetaManagedAgentsBase64DocumentSource struct{…}` + + Base64-encoded document data. + + - `Data string` + + Base64-encoded document data. + + - `MediaType string` + + MIME type of the document (e.g., "application/pdf"). + + - `Type BetaManagedAgentsBase64DocumentSourceType` + + - `const BetaManagedAgentsBase64DocumentSourceTypeBase64 BetaManagedAgentsBase64DocumentSourceType = "base64"` + + - `type BetaManagedAgentsPlainTextDocumentSource struct{…}` + + Plain text document content. + + - `Data string` + + The plain text content. + + - `MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType` + + MIME type of the text content. Must be "text/plain". + + - `const BetaManagedAgentsPlainTextDocumentSourceMediaTypeTextPlain BetaManagedAgentsPlainTextDocumentSourceMediaType = "text/plain"` + + - `Type BetaManagedAgentsPlainTextDocumentSourceType` + + - `const BetaManagedAgentsPlainTextDocumentSourceTypeText BetaManagedAgentsPlainTextDocumentSourceType = "text"` + + - `type BetaManagedAgentsURLDocumentSource struct{…}` + + Document referenced by URL. + + - `Type BetaManagedAgentsURLDocumentSourceType` + + - `const BetaManagedAgentsURLDocumentSourceTypeURL BetaManagedAgentsURLDocumentSourceType = "url"` + + - `URL string` + + URL of the document to fetch. + + - `type BetaManagedAgentsFileDocumentSource struct{…}` + + Document referenced by file ID. + + - `FileID string` + + ID of a previously uploaded file. + + - `Type BetaManagedAgentsFileDocumentSourceType` + + - `const BetaManagedAgentsFileDocumentSourceTypeFile BetaManagedAgentsFileDocumentSourceType = "file"` + + - `Type BetaManagedAgentsDocumentBlockType` + + - `const BetaManagedAgentsDocumentBlockTypeDocument BetaManagedAgentsDocumentBlockType = "document"` + + - `Context string` + + Additional context about the document for the model. + + - `Title string` + + The title of the document. + + - `IsError bool` + + Whether the tool execution resulted in an error. + + - `type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}` + + Indicates that context compaction (summarization) occurred during the session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsAgentThreadContextCompactedEventType` + + - `const BetaManagedAgentsAgentThreadContextCompactedEventTypeAgentThreadContextCompacted BetaManagedAgentsAgentThreadContextCompactedEventType = "agent.thread_context_compacted"` + + - `type BetaManagedAgentsSessionErrorEvent struct{…}` + + An error event indicating a problem occurred during session execution. + + - `ID string` + + Unique identifier for this event. + + - `Error BetaManagedAgentsSessionErrorEventErrorUnion` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `type BetaManagedAgentsUnknownError struct{…}` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsUnknownErrorType` + + - `const BetaManagedAgentsUnknownErrorTypeUnknownError BetaManagedAgentsUnknownErrorType = "unknown_error"` + + - `type BetaManagedAgentsModelOverloadedError struct{…}` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelOverloadedErrorType` + + - `const BetaManagedAgentsModelOverloadedErrorTypeModelOverloadedError BetaManagedAgentsModelOverloadedErrorType = "model_overloaded_error"` + + - `type BetaManagedAgentsModelRateLimitedError struct{…}` + + The model request was rate-limited. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRateLimitedErrorType` + + - `const BetaManagedAgentsModelRateLimitedErrorTypeModelRateLimitedError BetaManagedAgentsModelRateLimitedErrorType = "model_rate_limited_error"` + + - `type BetaManagedAgentsModelRequestFailedError struct{…}` + + A model request failed for a reason other than overload or rate-limiting. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsModelRequestFailedErrorType` + + - `const BetaManagedAgentsModelRequestFailedErrorTypeModelRequestFailedError BetaManagedAgentsModelRequestFailedErrorType = "model_request_failed_error"` + + - `type BetaManagedAgentsMCPConnectionFailedError struct{…}` + + Failed to connect to an MCP server. + + - `MCPServerName string` + + Name of the MCP server that failed to connect. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPConnectionFailedErrorType` + + - `const BetaManagedAgentsMCPConnectionFailedErrorTypeMCPConnectionFailedError BetaManagedAgentsMCPConnectionFailedErrorType = "mcp_connection_failed_error"` + + - `type BetaManagedAgentsMCPAuthenticationFailedError struct{…}` + + Authentication to an MCP server failed. + + - `MCPServerName string` + + Name of the MCP server that failed authentication. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsMCPAuthenticationFailedErrorType` + + - `const BetaManagedAgentsMCPAuthenticationFailedErrorTypeMCPAuthenticationFailedError BetaManagedAgentsMCPAuthenticationFailedErrorType = "mcp_authentication_failed_error"` + + - `type BetaManagedAgentsBillingError struct{…}` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `Message string` + + Human-readable error description. + + - `RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion` + + What the client should do next in response to this error. + + - `type BetaManagedAgentsRetryStatusRetrying struct{…}` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type BetaManagedAgentsRetryStatusRetryingType` + + - `const BetaManagedAgentsRetryStatusRetryingTypeRetrying BetaManagedAgentsRetryStatusRetryingType = "retrying"` + + - `type BetaManagedAgentsRetryStatusExhausted struct{…}` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type BetaManagedAgentsRetryStatusExhaustedType` + + - `const BetaManagedAgentsRetryStatusExhaustedTypeExhausted BetaManagedAgentsRetryStatusExhaustedType = "exhausted"` + + - `type BetaManagedAgentsRetryStatusTerminal struct{…}` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type BetaManagedAgentsRetryStatusTerminalType` + + - `const BetaManagedAgentsRetryStatusTerminalTypeTerminal BetaManagedAgentsRetryStatusTerminalType = "terminal"` + + - `Type BetaManagedAgentsBillingErrorType` + + - `const BetaManagedAgentsBillingErrorTypeBillingError BetaManagedAgentsBillingErrorType = "billing_error"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionErrorEventType` + + - `const BetaManagedAgentsSessionErrorEventTypeSessionError BetaManagedAgentsSessionErrorEventType = "session.error"` + + - `type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRescheduledEventType` + + - `const BetaManagedAgentsSessionStatusRescheduledEventTypeSessionStatusRescheduled BetaManagedAgentsSessionStatusRescheduledEventType = "session.status_rescheduled"` + + - `type BetaManagedAgentsSessionStatusRunningEvent struct{…}` + + Indicates the session is actively running and the agent is working. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusRunningEventType` + + - `const BetaManagedAgentsSessionStatusRunningEventTypeSessionStatusRunning BetaManagedAgentsSessionStatusRunningEventType = "session.status_running"` + + - `type BetaManagedAgentsSessionStatusIdleEvent struct{…}` + + Indicates the agent has paused and is awaiting user input. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion` + + The agent completed its turn naturally and is ready for the next user message. + + - `type BetaManagedAgentsSessionEndTurn struct{…}` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type BetaManagedAgentsSessionEndTurnType` + + - `const BetaManagedAgentsSessionEndTurnTypeEndTurn BetaManagedAgentsSessionEndTurnType = "end_turn"` + + - `type BetaManagedAgentsSessionRequiresAction struct{…}` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `EventIDs []string` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type BetaManagedAgentsSessionRequiresActionType` + + - `const BetaManagedAgentsSessionRequiresActionTypeRequiresAction BetaManagedAgentsSessionRequiresActionType = "requires_action"` + + - `type BetaManagedAgentsSessionRetriesExhausted struct{…}` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type BetaManagedAgentsSessionRetriesExhaustedType` + + - `const BetaManagedAgentsSessionRetriesExhaustedTypeRetriesExhausted BetaManagedAgentsSessionRetriesExhaustedType = "retries_exhausted"` + + - `Type BetaManagedAgentsSessionStatusIdleEventType` + + - `const BetaManagedAgentsSessionStatusIdleEventTypeSessionStatusIdle BetaManagedAgentsSessionStatusIdleEventType = "session.status_idle"` + + - `type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}` + + Indicates the session has terminated, either due to an error or completion. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionStatusTerminatedEventType` + + - `const BetaManagedAgentsSessionStatusTerminatedEventTypeSessionStatusTerminated BetaManagedAgentsSessionStatusTerminatedEventType = "session.status_terminated"` + + - `type BetaManagedAgentsSpanModelRequestStartEvent struct{…}` + + Emitted when a model request is initiated by the agent. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestStartEventType` + + - `const BetaManagedAgentsSpanModelRequestStartEventTypeSpanModelRequestStart BetaManagedAgentsSpanModelRequestStartEventType = "span.model_request_start"` + + - `type BetaManagedAgentsSpanModelRequestEndEvent struct{…}` + + Emitted when a model request completes. + + - `ID string` + + Unique identifier for this event. + + - `IsError bool` + + Whether the model request resulted in an error. + + - `ModelRequestStartID string` + + The id of the corresponding `span.model_request_start` event. + + - `ModelUsage BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `CacheCreationInputTokens int64` + + Tokens used to create prompt cache in this request. + + - `CacheReadInputTokens int64` + + Tokens read from prompt cache in this request. + + - `InputTokens int64` + + Input tokens consumed by this request. + + - `OutputTokens int64` + + Output tokens generated by this request. + + - `Speed BetaManagedAgentsSpanModelUsageSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"` + + - `const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"` + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSpanModelRequestEndEventType` + + - `const BetaManagedAgentsSpanModelRequestEndEventTypeSpanModelRequestEnd BetaManagedAgentsSpanModelRequestEndEventType = "span.model_request_end"` + + - `type BetaManagedAgentsSessionDeletedEvent struct{…}` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `ID string` + + Unique identifier for this event. + + - `ProcessedAt Time` + + A timestamp in RFC 3339 format + + - `Type BetaManagedAgentsSessionDeletedEventType` + + - `const BetaManagedAgentsSessionDeletedEventTypeSessionDeleted BetaManagedAgentsSessionDeletedEventType = "session.deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + stream := client.Beta.Sessions.Events.StreamEvents( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionEventStreamParams{ + + }, + ) + for stream.Next() { + fmt.Printf("%+v\n", stream.Current()) + } + err := stream.Err() + if err != nil { + panic(err.Error()) + } +} +``` diff --git a/content/en/api/go/beta/sessions/list.md b/content/en/api/go/beta/sessions/list.md new file mode 100644 index 000000000..ae84bf50d --- /dev/null +++ b/content/en/api/go/beta/sessions/list.md @@ -0,0 +1,562 @@ +## List + +`client.Beta.Sessions.List(ctx, params) (*PageCursor[BetaManagedAgentsSession], error)` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `params BetaSessionListParams` + + - `AgentID param.Field[string]` + + Query param: Filter sessions created with this agent ID. + + - `AgentVersion param.Field[int64]` + + Query param: Filter by agent version. Only applies when agent_id is also set. + + - `CreatedAtGt param.Field[Time]` + + Query param: Return sessions created after this time (exclusive). + + - `CreatedAtGte param.Field[Time]` + + Query param: Return sessions created at or after this time (inclusive). + + - `CreatedAtLt param.Field[Time]` + + Query param: Return sessions created before this time (exclusive). + + - `CreatedAtLte param.Field[Time]` + + Query param: Return sessions created at or before this time (inclusive). + + - `IncludeArchived param.Field[bool]` + + Query param: When true, includes archived sessions. Default: false (exclude archived). + + - `Limit param.Field[int64]` + + Query param: Maximum number of results to return. + + - `Order param.Field[BetaSessionListParamsOrder]` + + Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `const BetaSessionListParamsOrderAsc BetaSessionListParamsOrder = "asc"` + + - `const BetaSessionListParamsOrderDesc BetaSessionListParamsOrder = "desc"` + + - `Page param.Field[string]` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Sessions.List(context.TODO(), anthropic.BetaSessionListParams{ + + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` diff --git a/content/en/api/go/beta/sessions/resources.md b/content/en/api/go/beta/sessions/resources.md new file mode 100644 index 000000000..401f30e20 --- /dev/null +++ b/content/en/api/go/beta/sessions/resources.md @@ -0,0 +1,890 @@ +# Resources + +## Add + +`client.Beta.Sessions.Resources.Add(ctx, sessionID, params) (*BetaManagedAgentsFileResource, error)` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `sessionID string` + +- `params BetaSessionResourceAddParams` + + - `BetaManagedAgentsFileResourceParams param.Field[BetaManagedAgentsFileResourceParamsResp]` + + Body param: Mount a file uploaded via the Files API into the session. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsFileResource, err := client.Beta.Sessions.Resources.Add( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionResourceAddParams{ + BetaManagedAgentsFileResourceParams: anthropic.BetaManagedAgentsFileResourceParams{ + FileID: "file_011CNha8iCJcU1wXNR6q4V8w", + Type: anthropic.BetaManagedAgentsFileResourceParamsTypeFile, + }, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsFileResource.ID) +} +``` + +## List + +`client.Beta.Sessions.Resources.List(ctx, sessionID, params) (*PageCursor[BetaManagedAgentsSessionResourceUnion], error)` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `sessionID string` + +- `params BetaSessionResourceListParams` + + - `Limit param.Field[int64]` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `Page param.Field[string]` + + Query param: Opaque cursor from a previous response's next_page field. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSessionResourceUnion interface{…}` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Sessions.Resources.List( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionResourceListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Sessions.Resources.Get(ctx, resourceID, params) (*BetaSessionResourceGetResponseUnion, error)` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `resourceID string` + +- `params BetaSessionResourceGetParams` + + - `SessionID param.Field[string]` + + Path param: Path parameter session_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaSessionResourceGetResponseUnion interface{…}` + + The requested session resource. + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + resource, err := client.Beta.Sessions.Resources.Get( + context.TODO(), + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + anthropic.BetaSessionResourceGetParams{ + SessionID: "sesn_011CZkZAtmR3yMPDzynEDxu7", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", resource) +} +``` + +## Update + +`client.Beta.Sessions.Resources.Update(ctx, resourceID, params) (*BetaSessionResourceUpdateResponseUnion, error)` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `resourceID string` + +- `params BetaSessionResourceUpdateParams` + + - `SessionID param.Field[string]` + + Path param: Path parameter session_id + + - `AuthorizationToken param.Field[string]` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaSessionResourceUpdateResponseUnion interface{…}` + + The updated session resource. + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + resource, err := client.Beta.Sessions.Resources.Update( + context.TODO(), + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + anthropic.BetaSessionResourceUpdateParams{ + SessionID: "sesn_011CZkZAtmR3yMPDzynEDxu7", + AuthorizationToken: "ghp_exampletoken", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", resource) +} +``` + +## Delete + +`client.Beta.Sessions.Resources.Delete(ctx, resourceID, params) (*BetaManagedAgentsDeleteSessionResource, error)` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `resourceID string` + +- `params BetaSessionResourceDeleteParams` + + - `SessionID param.Field[string]` + + Path param: Path parameter session_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeleteSessionResource struct{…}` + + Confirmation of resource deletion. + + - `ID string` + + - `Type BetaManagedAgentsDeleteSessionResourceType` + + - `const BetaManagedAgentsDeleteSessionResourceTypeSessionResourceDeleted BetaManagedAgentsDeleteSessionResourceType = "session_resource_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeleteSessionResource, err := client.Beta.Sessions.Resources.Delete( + context.TODO(), + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + anthropic.BetaSessionResourceDeleteParams{ + SessionID: "sesn_011CZkZAtmR3yMPDzynEDxu7", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeleteSessionResource.ID) +} +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `type BetaManagedAgentsDeleteSessionResource struct{…}` + + Confirmation of resource deletion. + + - `ID string` + + - `Type BetaManagedAgentsDeleteSessionResourceType` + + - `const BetaManagedAgentsDeleteSessionResourceTypeSessionResourceDeleted BetaManagedAgentsDeleteSessionResourceType = "session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + +### Beta Managed Agents Session Resource + +- `type BetaManagedAgentsSessionResourceUnion interface{…}` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format diff --git a/content/en/api/go/beta/sessions/resources/add.md b/content/en/api/go/beta/sessions/resources/add.md new file mode 100644 index 000000000..27e9683e4 --- /dev/null +++ b/content/en/api/go/beta/sessions/resources/add.md @@ -0,0 +1,123 @@ +## Add + +`client.Beta.Sessions.Resources.Add(ctx, sessionID, params) (*BetaManagedAgentsFileResource, error)` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `sessionID string` + +- `params BetaSessionResourceAddParams` + + - `BetaManagedAgentsFileResourceParams param.Field[BetaManagedAgentsFileResourceParamsResp]` + + Body param: Mount a file uploaded via the Files API into the session. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsFileResource, err := client.Beta.Sessions.Resources.Add( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionResourceAddParams{ + BetaManagedAgentsFileResourceParams: anthropic.BetaManagedAgentsFileResourceParams{ + FileID: "file_011CNha8iCJcU1wXNR6q4V8w", + Type: anthropic.BetaManagedAgentsFileResourceParamsTypeFile, + }, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsFileResource.ID) +} +``` diff --git a/content/en/api/go/beta/sessions/resources/delete.md b/content/en/api/go/beta/sessions/resources/delete.md new file mode 100644 index 000000000..3ed9c61ba --- /dev/null +++ b/content/en/api/go/beta/sessions/resources/delete.md @@ -0,0 +1,110 @@ +## Delete + +`client.Beta.Sessions.Resources.Delete(ctx, resourceID, params) (*BetaManagedAgentsDeleteSessionResource, error)` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `resourceID string` + +- `params BetaSessionResourceDeleteParams` + + - `SessionID param.Field[string]` + + Path param: Path parameter session_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeleteSessionResource struct{…}` + + Confirmation of resource deletion. + + - `ID string` + + - `Type BetaManagedAgentsDeleteSessionResourceType` + + - `const BetaManagedAgentsDeleteSessionResourceTypeSessionResourceDeleted BetaManagedAgentsDeleteSessionResourceType = "session_resource_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeleteSessionResource, err := client.Beta.Sessions.Resources.Delete( + context.TODO(), + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + anthropic.BetaSessionResourceDeleteParams{ + SessionID: "sesn_011CZkZAtmR3yMPDzynEDxu7", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeleteSessionResource.ID) +} +``` diff --git a/content/en/api/go/beta/sessions/resources/list.md b/content/en/api/go/beta/sessions/resources/list.md new file mode 100644 index 000000000..a91ccee47 --- /dev/null +++ b/content/en/api/go/beta/sessions/resources/list.md @@ -0,0 +1,168 @@ +## List + +`client.Beta.Sessions.Resources.List(ctx, sessionID, params) (*PageCursor[BetaManagedAgentsSessionResourceUnion], error)` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `sessionID string` + +- `params BetaSessionResourceListParams` + + - `Limit param.Field[int64]` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `Page param.Field[string]` + + Query param: Opaque cursor from a previous response's next_page field. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSessionResourceUnion interface{…}` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Sessions.Resources.List( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionResourceListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` diff --git a/content/en/api/go/beta/sessions/resources/retrieve.md b/content/en/api/go/beta/sessions/resources/retrieve.md new file mode 100644 index 000000000..e2e5813cf --- /dev/null +++ b/content/en/api/go/beta/sessions/resources/retrieve.md @@ -0,0 +1,166 @@ +## Retrieve + +`client.Beta.Sessions.Resources.Get(ctx, resourceID, params) (*BetaSessionResourceGetResponseUnion, error)` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `resourceID string` + +- `params BetaSessionResourceGetParams` + + - `SessionID param.Field[string]` + + Path param: Path parameter session_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaSessionResourceGetResponseUnion interface{…}` + + The requested session resource. + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + resource, err := client.Beta.Sessions.Resources.Get( + context.TODO(), + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + anthropic.BetaSessionResourceGetParams{ + SessionID: "sesn_011CZkZAtmR3yMPDzynEDxu7", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", resource) +} +``` diff --git a/content/en/api/go/beta/sessions/resources/update.md b/content/en/api/go/beta/sessions/resources/update.md new file mode 100644 index 000000000..9d18a95d9 --- /dev/null +++ b/content/en/api/go/beta/sessions/resources/update.md @@ -0,0 +1,171 @@ +## Update + +`client.Beta.Sessions.Resources.Update(ctx, resourceID, params) (*BetaSessionResourceUpdateResponseUnion, error)` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `resourceID string` + +- `params BetaSessionResourceUpdateParams` + + - `SessionID param.Field[string]` + + Path param: Path parameter session_id + + - `AuthorizationToken param.Field[string]` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaSessionResourceUpdateResponseUnion interface{…}` + + The updated session resource. + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + resource, err := client.Beta.Sessions.Resources.Update( + context.TODO(), + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + anthropic.BetaSessionResourceUpdateParams{ + SessionID: "sesn_011CZkZAtmR3yMPDzynEDxu7", + AuthorizationToken: "ghp_exampletoken", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", resource) +} +``` diff --git a/content/en/api/go/beta/sessions/retrieve.md b/content/en/api/go/beta/sessions/retrieve.md new file mode 100644 index 000000000..6f95e5c92 --- /dev/null +++ b/content/en/api/go/beta/sessions/retrieve.md @@ -0,0 +1,524 @@ +## Retrieve + +`client.Beta.Sessions.Get(ctx, sessionID, query) (*BetaManagedAgentsSession, error)` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `sessionID string` + +- `query BetaSessionGetParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSession, err := client.Beta.Sessions.Get( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionGetParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSession.ID) +} +``` diff --git a/content/en/api/go/beta/sessions/update.md b/content/en/api/go/beta/sessions/update.md new file mode 100644 index 000000000..2c2d1127d --- /dev/null +++ b/content/en/api/go/beta/sessions/update.md @@ -0,0 +1,536 @@ +## Update + +`client.Beta.Sessions.Update(ctx, sessionID, params) (*BetaManagedAgentsSession, error)` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `sessionID string` + +- `params BetaSessionUpdateParams` + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + + - `Title param.Field[string]` + + Body param: Human-readable session title. + + - `VaultIDs param.Field[[]string]` + + Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsSession struct{…}` + + A Managed Agents `session`. + + - `ID string` + + - `Agent BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `ID string` + + - `Description string` + + - `MCPServers []BetaManagedAgentsMCPServerURLDefinition` + + - `Name string` + + - `Type BetaManagedAgentsMCPServerURLDefinitionType` + + - `const BetaManagedAgentsMCPServerURLDefinitionTypeURL BetaManagedAgentsMCPServerURLDefinitionType = "url"` + + - `URL string` + + - `Model BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `ID BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `type BetaManagedAgentsModel string` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `const BetaManagedAgentsModelClaudeOpus4_6 BetaManagedAgentsModel = "claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_6 BetaManagedAgentsModel = "claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5 BetaManagedAgentsModel = "claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeHaiku4_5_20251001 BetaManagedAgentsModel = "claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `const BetaManagedAgentsModelClaudeOpus4_5 BetaManagedAgentsModel = "claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeOpus4_5_20251101 BetaManagedAgentsModel = "claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `const BetaManagedAgentsModelClaudeSonnet4_5 BetaManagedAgentsModel = "claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `const BetaManagedAgentsModelClaudeSonnet4_5_20250929 BetaManagedAgentsModel = "claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `string` + + - `Speed BetaManagedAgentsModelConfigSpeed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `const BetaManagedAgentsModelConfigSpeedStandard BetaManagedAgentsModelConfigSpeed = "standard"` + + - `const BetaManagedAgentsModelConfigSpeedFast BetaManagedAgentsModelConfigSpeed = "fast"` + + - `Name string` + + - `Skills []BetaManagedAgentsSessionAgentSkillUnion` + + - `type BetaManagedAgentsAnthropicSkill struct{…}` + + A resolved Anthropic-managed skill. + + - `SkillID string` + + - `Type BetaManagedAgentsAnthropicSkillType` + + - `const BetaManagedAgentsAnthropicSkillTypeAnthropic BetaManagedAgentsAnthropicSkillType = "anthropic"` + + - `Version string` + + - `type BetaManagedAgentsCustomSkill struct{…}` + + A resolved user-created custom skill. + + - `SkillID string` + + - `Type BetaManagedAgentsCustomSkillType` + + - `const BetaManagedAgentsCustomSkillTypeCustom BetaManagedAgentsCustomSkillType = "custom"` + + - `Version string` + + - `System string` + + - `Tools []BetaManagedAgentsSessionAgentToolUnion` + + - `type BetaManagedAgentsAgentToolset20260401 struct{…}` + + - `Configs []BetaManagedAgentsAgentToolConfig` + + - `Enabled bool` + + - `Name BetaManagedAgentsAgentToolConfigName` + + Built-in agent tool identifier. + + - `const BetaManagedAgentsAgentToolConfigNameBash BetaManagedAgentsAgentToolConfigName = "bash"` + + - `const BetaManagedAgentsAgentToolConfigNameEdit BetaManagedAgentsAgentToolConfigName = "edit"` + + - `const BetaManagedAgentsAgentToolConfigNameRead BetaManagedAgentsAgentToolConfigName = "read"` + + - `const BetaManagedAgentsAgentToolConfigNameWrite BetaManagedAgentsAgentToolConfigName = "write"` + + - `const BetaManagedAgentsAgentToolConfigNameGlob BetaManagedAgentsAgentToolConfigName = "glob"` + + - `const BetaManagedAgentsAgentToolConfigNameGrep BetaManagedAgentsAgentToolConfigName = "grep"` + + - `const BetaManagedAgentsAgentToolConfigNameWebFetch BetaManagedAgentsAgentToolConfigName = "web_fetch"` + + - `const BetaManagedAgentsAgentToolConfigNameWebSearch BetaManagedAgentsAgentToolConfigName = "web_search"` + + - `PermissionPolicy BetaManagedAgentsAgentToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsAgentToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `Type BetaManagedAgentsAgentToolset20260401Type` + + - `const BetaManagedAgentsAgentToolset20260401TypeAgentToolset20260401 BetaManagedAgentsAgentToolset20260401Type = "agent_toolset_20260401"` + + - `type BetaManagedAgentsMCPToolset struct{…}` + + - `Configs []BetaManagedAgentsMCPToolConfig` + + - `Enabled bool` + + - `Name string` + + - `PermissionPolicy BetaManagedAgentsMCPToolConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `DefaultConfig BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `Enabled bool` + + - `PermissionPolicy BetaManagedAgentsMCPToolsetDefaultConfigPermissionPolicyUnion` + + Permission policy for tool execution. + + - `type BetaManagedAgentsAlwaysAllowPolicy struct{…}` + + Tool calls are automatically approved without user confirmation. + + - `Type BetaManagedAgentsAlwaysAllowPolicyType` + + - `const BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow BetaManagedAgentsAlwaysAllowPolicyType = "always_allow"` + + - `type BetaManagedAgentsAlwaysAskPolicy struct{…}` + + Tool calls require user confirmation before execution. + + - `Type BetaManagedAgentsAlwaysAskPolicyType` + + - `const BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk BetaManagedAgentsAlwaysAskPolicyType = "always_ask"` + + - `MCPServerName string` + + - `Type BetaManagedAgentsMCPToolsetType` + + - `const BetaManagedAgentsMCPToolsetTypeMCPToolset BetaManagedAgentsMCPToolsetType = "mcp_toolset"` + + - `type BetaManagedAgentsCustomTool struct{…}` + + A custom tool as returned in API responses. + + - `Description string` + + - `InputSchema BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `Properties map[string, any]` + + JSON Schema properties defining the tool's input parameters. + + - `Required []string` + + List of required property names. + + - `Type BetaManagedAgentsCustomToolInputSchemaType` + + Must be 'object' for tool input schemas. + + - `const BetaManagedAgentsCustomToolInputSchemaTypeObject BetaManagedAgentsCustomToolInputSchemaType = "object"` + + - `Name string` + + - `Type BetaManagedAgentsCustomToolType` + + - `const BetaManagedAgentsCustomToolTypeCustom BetaManagedAgentsCustomToolType = "custom"` + + - `Type BetaManagedAgentsSessionAgentType` + + - `const BetaManagedAgentsSessionAgentTypeAgent BetaManagedAgentsSessionAgentType = "agent"` + + - `Version int64` + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `EnvironmentID string` + + - `Metadata map[string, string]` + + - `Resources []BetaManagedAgentsSessionResourceUnion` + + - `type BetaManagedAgentsGitHubRepositoryResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `MountPath string` + + - `Type BetaManagedAgentsGitHubRepositoryResourceType` + + - `const BetaManagedAgentsGitHubRepositoryResourceTypeGitHubRepository BetaManagedAgentsGitHubRepositoryResourceType = "github_repository"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `URL string` + + - `Checkout BetaManagedAgentsGitHubRepositoryResourceCheckoutUnion` + + - `type BetaManagedAgentsBranchCheckout struct{…}` + + - `Name string` + + Branch name to check out. + + - `Type BetaManagedAgentsBranchCheckoutType` + + - `const BetaManagedAgentsBranchCheckoutTypeBranch BetaManagedAgentsBranchCheckoutType = "branch"` + + - `type BetaManagedAgentsCommitCheckout struct{…}` + + - `Sha string` + + Full commit SHA to check out. + + - `Type BetaManagedAgentsCommitCheckoutType` + + - `const BetaManagedAgentsCommitCheckoutTypeCommit BetaManagedAgentsCommitCheckoutType = "commit"` + + - `type BetaManagedAgentsFileResource struct{…}` + + - `ID string` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `FileID string` + + - `MountPath string` + + - `Type BetaManagedAgentsFileResourceType` + + - `const BetaManagedAgentsFileResourceTypeFile BetaManagedAgentsFileResourceType = "file"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Stats BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `ActiveSeconds float64` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `DurationSeconds float64` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status BetaManagedAgentsSessionStatus` + + SessionStatus enum + + - `const BetaManagedAgentsSessionStatusRescheduling BetaManagedAgentsSessionStatus = "rescheduling"` + + - `const BetaManagedAgentsSessionStatusRunning BetaManagedAgentsSessionStatus = "running"` + + - `const BetaManagedAgentsSessionStatusIdle BetaManagedAgentsSessionStatus = "idle"` + + - `const BetaManagedAgentsSessionStatusTerminated BetaManagedAgentsSessionStatus = "terminated"` + + - `Title string` + + - `Type BetaManagedAgentsSessionType` + + - `const BetaManagedAgentsSessionTypeSession BetaManagedAgentsSessionType = "session"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `Usage BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `CacheCreation BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Ephemeral1hInputTokens int64` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Ephemeral5mInputTokens int64` + + Tokens used to create 5-minute ephemeral cache entries. + + - `CacheReadInputTokens int64` + + Total tokens read from prompt cache. + + - `InputTokens int64` + + Total input tokens consumed across all turns. + + - `OutputTokens int64` + + Total output tokens generated across all turns. + + - `VaultIDs []string` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsSession, err := client.Beta.Sessions.Update( + context.TODO(), + "sesn_011CZkZAtmR3yMPDzynEDxu7", + anthropic.BetaSessionUpdateParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsSession.ID) +} +``` diff --git a/content/en/api/go/beta/skills.md b/content/en/api/go/beta/skills.md index e104f2dd6..bb35a0aef 100644 --- a/content/en/api/go/beta/skills.md +++ b/content/en/api/go/beta/skills.md @@ -74,8 +74,6 @@ Create Skill - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillNewResponse struct{…}` @@ -231,8 +229,6 @@ List Skills - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillListResponse struct{…}` @@ -373,8 +369,6 @@ Get Skill - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillGetResponse struct{…}` @@ -519,8 +513,6 @@ Delete Skill - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillDeleteResponse struct{…}` @@ -644,8 +636,6 @@ Create Skill Version - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillVersionNewResponse struct{…}` @@ -803,8 +793,6 @@ List Skill Versions - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillVersionListResponse struct{…}` @@ -958,8 +946,6 @@ Get Skill Version - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillVersionGetResponse struct{…}` @@ -1113,8 +1099,6 @@ Delete Skill Version - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillVersionDeleteResponse struct{…}` diff --git a/content/en/api/go/beta/skills/create.md b/content/en/api/go/beta/skills/create.md index 367ffa1e3..0d7f95b88 100644 --- a/content/en/api/go/beta/skills/create.md +++ b/content/en/api/go/beta/skills/create.md @@ -72,8 +72,6 @@ Create Skill - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillNewResponse struct{…}` diff --git a/content/en/api/go/beta/skills/delete.md b/content/en/api/go/beta/skills/delete.md index d63fefd3b..d4f9c4c23 100644 --- a/content/en/api/go/beta/skills/delete.md +++ b/content/en/api/go/beta/skills/delete.md @@ -66,8 +66,6 @@ Delete Skill - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillDeleteResponse struct{…}` diff --git a/content/en/api/go/beta/skills/list.md b/content/en/api/go/beta/skills/list.md index cf9bb27de..b6b306b1b 100644 --- a/content/en/api/go/beta/skills/list.md +++ b/content/en/api/go/beta/skills/list.md @@ -81,8 +81,6 @@ List Skills - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillListResponse struct{…}` diff --git a/content/en/api/go/beta/skills/retrieve.md b/content/en/api/go/beta/skills/retrieve.md index 115d1ad55..c62d62f63 100644 --- a/content/en/api/go/beta/skills/retrieve.md +++ b/content/en/api/go/beta/skills/retrieve.md @@ -66,8 +66,6 @@ Get Skill - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillGetResponse struct{…}` diff --git a/content/en/api/go/beta/skills/versions.md b/content/en/api/go/beta/skills/versions.md index c59b92866..5007d92e3 100644 --- a/content/en/api/go/beta/skills/versions.md +++ b/content/en/api/go/beta/skills/versions.md @@ -74,8 +74,6 @@ Create Skill Version - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillVersionNewResponse struct{…}` @@ -233,8 +231,6 @@ List Skill Versions - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillVersionListResponse struct{…}` @@ -388,8 +384,6 @@ Get Skill Version - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillVersionGetResponse struct{…}` @@ -543,8 +537,6 @@ Delete Skill Version - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillVersionDeleteResponse struct{…}` diff --git a/content/en/api/go/beta/skills/versions/create.md b/content/en/api/go/beta/skills/versions/create.md index 3c339f30d..71284f49a 100644 --- a/content/en/api/go/beta/skills/versions/create.md +++ b/content/en/api/go/beta/skills/versions/create.md @@ -72,8 +72,6 @@ Create Skill Version - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillVersionNewResponse struct{…}` diff --git a/content/en/api/go/beta/skills/versions/delete.md b/content/en/api/go/beta/skills/versions/delete.md index e7d734343..e3b8b96a6 100644 --- a/content/en/api/go/beta/skills/versions/delete.md +++ b/content/en/api/go/beta/skills/versions/delete.md @@ -72,8 +72,6 @@ Delete Skill Version - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillVersionDeleteResponse struct{…}` diff --git a/content/en/api/go/beta/skills/versions/list.md b/content/en/api/go/beta/skills/versions/list.md index 9d5920717..6ded72a73 100644 --- a/content/en/api/go/beta/skills/versions/list.md +++ b/content/en/api/go/beta/skills/versions/list.md @@ -76,8 +76,6 @@ List Skill Versions - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillVersionListResponse struct{…}` diff --git a/content/en/api/go/beta/skills/versions/retrieve.md b/content/en/api/go/beta/skills/versions/retrieve.md index c95d9c73b..8749aa144 100644 --- a/content/en/api/go/beta/skills/versions/retrieve.md +++ b/content/en/api/go/beta/skills/versions/retrieve.md @@ -72,8 +72,6 @@ Get Skill Version - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type BetaSkillVersionGetResponse struct{…}` diff --git a/content/en/api/go/beta/vaults.md b/content/en/api/go/beta/vaults.md new file mode 100644 index 000000000..e890fcefc --- /dev/null +++ b/content/en/api/go/beta/vaults.md @@ -0,0 +1,2855 @@ +# Vaults + +## Create + +`client.Beta.Vaults.New(ctx, params) (*BetaManagedAgentsVault, error)` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `params BetaVaultNewParams` + + - `DisplayName param.Field[string]` + + Body param: Human-readable name for the vault. 1-255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Arbitrary key-value metadata to attach to the vault. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsVault, err := client.Beta.Vaults.New(context.TODO(), anthropic.BetaVaultNewParams{ + DisplayName: "Example vault", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsVault.ID) +} +``` + +## List + +`client.Beta.Vaults.List(ctx, params) (*PageCursor[BetaManagedAgentsVault], error)` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `params BetaVaultListParams` + + - `IncludeArchived param.Field[bool]` + + Query param: Whether to include archived vaults in the results. + + - `Limit param.Field[int64]` + + Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination token from a previous `list_vaults` response. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Vaults.List(context.TODO(), anthropic.BetaVaultListParams{ + + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Vaults.Get(ctx, vaultID, query) (*BetaManagedAgentsVault, error)` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `vaultID string` + +- `query BetaVaultGetParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsVault, err := client.Beta.Vaults.Get( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultGetParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsVault.ID) +} +``` + +## Update + +`client.Beta.Vaults.Update(ctx, vaultID, params) (*BetaManagedAgentsVault, error)` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `vaultID string` + +- `params BetaVaultUpdateParams` + + - `DisplayName param.Field[string]` + + Body param: Updated human-readable name for the vault. 1-255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsVault, err := client.Beta.Vaults.Update( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultUpdateParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsVault.ID) +} +``` + +## Delete + +`client.Beta.Vaults.Delete(ctx, vaultID, body) (*BetaManagedAgentsDeletedVault, error)` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `vaultID string` + +- `body BetaVaultDeleteParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeletedVault struct{…}` + + Confirmation of a deleted vault. + + - `ID string` + + Unique identifier of the deleted vault. + + - `Type BetaManagedAgentsDeletedVaultType` + + - `const BetaManagedAgentsDeletedVaultTypeVaultDeleted BetaManagedAgentsDeletedVaultType = "vault_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeletedVault, err := client.Beta.Vaults.Delete( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultDeleteParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeletedVault.ID) +} +``` + +## Archive + +`client.Beta.Vaults.Archive(ctx, vaultID, body) (*BetaManagedAgentsVault, error)` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `vaultID string` + +- `body BetaVaultArchiveParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsVault, err := client.Beta.Vaults.Archive( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultArchiveParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsVault.ID) +} +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `type BetaManagedAgentsDeletedVault struct{…}` + + Confirmation of a deleted vault. + + - `ID string` + + Unique identifier of the deleted vault. + + - `Type BetaManagedAgentsDeletedVaultType` + + - `const BetaManagedAgentsDeletedVaultTypeVaultDeleted BetaManagedAgentsDeletedVaultType = "vault_deleted"` + +### Beta Managed Agents Vault + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`client.Beta.Vaults.Credentials.New(ctx, vaultID, params) (*BetaManagedAgentsCredential, error)` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vaultID string` + +- `params BetaVaultCredentialNewParams` + + - `Auth param.Field[BetaVaultCredentialNewParamsAuthUnion]` + + Body param: Authentication details for creating a credential. + + - `type BetaManagedAgentsMCPOAuthCreateParamsResp struct{…}` + + Parameters for creating an MCP OAuth credential. + + - `AccessToken string` + + OAuth access token. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthCreateParamsType` + + - `const BetaManagedAgentsMCPOAuthCreateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthCreateParamsType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshParamsResp` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `ClientID string` + + OAuth client ID. + + - `RefreshToken string` + + OAuth refresh token. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnionResp` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerCreateParamsResp struct{…}` + + Parameters for creating a static bearer token credential. + + - `Token string` + + Static bearer token value. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerCreateParamsType` + + - `const BetaManagedAgentsStaticBearerCreateParamsTypeStaticBearer BetaManagedAgentsStaticBearerCreateParamsType = "static_bearer"` + + - `DisplayName param.Field[string]` + + Body param: Human-readable name for the credential. Up to 255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Arbitrary key-value metadata to attach to the credential. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.New( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultCredentialNewParams{ + Auth: anthropic.BetaVaultCredentialNewParamsAuthUnion{ + OfStaticBearer: &anthropic.BetaManagedAgentsStaticBearerCreateParams{ + Token: "bearer_exampletoken", + MCPServerURL: "https://example-server.modelcontextprotocol.io/sse", + Type: anthropic.BetaManagedAgentsStaticBearerCreateParamsTypeStaticBearer, + }, + }, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` + +## List + +`client.Beta.Vaults.Credentials.List(ctx, vaultID, params) (*PageCursor[BetaManagedAgentsCredential], error)` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vaultID string` + +- `params BetaVaultCredentialListParams` + + - `IncludeArchived param.Field[bool]` + + Query param: Whether to include archived credentials in the results. + + - `Limit param.Field[int64]` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination token from a previous `list_credentials` response. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Vaults.Credentials.List( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultCredentialListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Vaults.Credentials.Get(ctx, credentialID, params) (*BetaManagedAgentsCredential, error)` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialGetParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.Get( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialGetParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` + +## Update + +`client.Beta.Vaults.Credentials.Update(ctx, credentialID, params) (*BetaManagedAgentsCredential, error)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialUpdateParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Auth param.Field[BetaVaultCredentialUpdateParamsAuthUnion]` + + Body param: Updated authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthUpdateParamsResp struct{…}` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsMCPOAuthUpdateParamsType` + + - `const BetaManagedAgentsMCPOAuthUpdateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthUpdateParamsType = "mcp_oauth"` + + - `AccessToken string` + + Updated OAuth access token. + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshUpdateParamsResp` + + Parameters for updating OAuth refresh token configuration. + + - `RefreshToken string` + + Updated OAuth refresh token. + + - `Scope string` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshUpdateParamsTokenEndpointAuthUnionResp` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` + + Updated POST body authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsStaticBearerUpdateParamsResp struct{…}` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsStaticBearerUpdateParamsType` + + - `const BetaManagedAgentsStaticBearerUpdateParamsTypeStaticBearer BetaManagedAgentsStaticBearerUpdateParamsType = "static_bearer"` + + - `Token string` + + Updated static bearer token value. + + - `DisplayName param.Field[string]` + + Body param: Updated human-readable name for the credential. 1-255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.Update( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialUpdateParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` + +## Delete + +`client.Beta.Vaults.Credentials.Delete(ctx, credentialID, params) (*BetaManagedAgentsDeletedCredential, error)` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialDeleteParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeletedCredential struct{…}` + + Confirmation of a deleted credential. + + - `ID string` + + Unique identifier of the deleted credential. + + - `Type BetaManagedAgentsDeletedCredentialType` + + - `const BetaManagedAgentsDeletedCredentialTypeVaultCredentialDeleted BetaManagedAgentsDeletedCredentialType = "vault_credential_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeletedCredential, err := client.Beta.Vaults.Credentials.Delete( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialDeleteParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeletedCredential.ID) +} +``` + +## Archive + +`client.Beta.Vaults.Credentials.Archive(ctx, credentialID, params) (*BetaManagedAgentsCredential, error)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialArchiveParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.Archive( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialArchiveParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `type BetaManagedAgentsDeletedCredential struct{…}` + + Confirmation of a deleted credential. + + - `ID string` + + Unique identifier of the deleted credential. + + - `Type BetaManagedAgentsDeletedCredentialType` + + - `const BetaManagedAgentsDeletedCredentialTypeVaultCredentialDeleted BetaManagedAgentsDeletedCredentialType = "vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `type BetaManagedAgentsMCPOAuthCreateParamsResp struct{…}` + + Parameters for creating an MCP OAuth credential. + + - `AccessToken string` + + OAuth access token. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthCreateParamsType` + + - `const BetaManagedAgentsMCPOAuthCreateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthCreateParamsType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshParamsResp` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `ClientID string` + + OAuth client ID. + + - `RefreshToken string` + + OAuth refresh token. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnionResp` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `type BetaManagedAgentsMCPOAuthRefreshParamsResp struct{…}` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `ClientID string` + + OAuth client ID. + + - `RefreshToken string` + + OAuth refresh token. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnionResp` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `type BetaManagedAgentsMCPOAuthRefreshResponse struct{…}` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `type BetaManagedAgentsMCPOAuthRefreshUpdateParamsResp struct{…}` + + Parameters for updating OAuth refresh token configuration. + + - `RefreshToken string` + + Updated OAuth refresh token. + + - `Scope string` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshUpdateParamsTokenEndpointAuthUnionResp` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` + + Updated POST body authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` + + - `ClientSecret string` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `type BetaManagedAgentsMCPOAuthUpdateParamsResp struct{…}` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsMCPOAuthUpdateParamsType` + + - `const BetaManagedAgentsMCPOAuthUpdateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthUpdateParamsType = "mcp_oauth"` + + - `AccessToken string` + + Updated OAuth access token. + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshUpdateParamsResp` + + Parameters for updating OAuth refresh token configuration. + + - `RefreshToken string` + + Updated OAuth refresh token. + + - `Scope string` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshUpdateParamsTokenEndpointAuthUnionResp` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` + + Updated POST body authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` + + - `ClientSecret string` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `type BetaManagedAgentsStaticBearerCreateParamsResp struct{…}` + + Parameters for creating a static bearer token credential. + + - `Token string` + + Static bearer token value. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerCreateParamsType` + + - `const BetaManagedAgentsStaticBearerCreateParamsTypeStaticBearer BetaManagedAgentsStaticBearerCreateParamsType = "static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `type BetaManagedAgentsStaticBearerUpdateParamsResp struct{…}` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsStaticBearerUpdateParamsType` + + - `const BetaManagedAgentsStaticBearerUpdateParamsTypeStaticBearer BetaManagedAgentsStaticBearerUpdateParamsType = "static_bearer"` + + - `Token string` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` + + - `ClientSecret string` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` + + Updated POST body authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` + + - `ClientSecret string` + + Updated OAuth client secret. diff --git a/content/en/api/go/beta/vaults/archive.md b/content/en/api/go/beta/vaults/archive.md new file mode 100644 index 000000000..8c6084082 --- /dev/null +++ b/content/en/api/go/beta/vaults/archive.md @@ -0,0 +1,128 @@ +## Archive + +`client.Beta.Vaults.Archive(ctx, vaultID, body) (*BetaManagedAgentsVault, error)` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `vaultID string` + +- `body BetaVaultArchiveParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsVault, err := client.Beta.Vaults.Archive( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultArchiveParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsVault.ID) +} +``` diff --git a/content/en/api/go/beta/vaults/create.md b/content/en/api/go/beta/vaults/create.md new file mode 100644 index 000000000..f651c82fb --- /dev/null +++ b/content/en/api/go/beta/vaults/create.md @@ -0,0 +1,130 @@ +## Create + +`client.Beta.Vaults.New(ctx, params) (*BetaManagedAgentsVault, error)` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `params BetaVaultNewParams` + + - `DisplayName param.Field[string]` + + Body param: Human-readable name for the vault. 1-255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Arbitrary key-value metadata to attach to the vault. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsVault, err := client.Beta.Vaults.New(context.TODO(), anthropic.BetaVaultNewParams{ + DisplayName: "Example vault", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsVault.ID) +} +``` diff --git a/content/en/api/go/beta/vaults/credentials.md b/content/en/api/go/beta/vaults/credentials.md new file mode 100644 index 000000000..f9751c290 --- /dev/null +++ b/content/en/api/go/beta/vaults/credentials.md @@ -0,0 +1,2033 @@ +# Credentials + +## Create + +`client.Beta.Vaults.Credentials.New(ctx, vaultID, params) (*BetaManagedAgentsCredential, error)` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vaultID string` + +- `params BetaVaultCredentialNewParams` + + - `Auth param.Field[BetaVaultCredentialNewParamsAuthUnion]` + + Body param: Authentication details for creating a credential. + + - `type BetaManagedAgentsMCPOAuthCreateParamsResp struct{…}` + + Parameters for creating an MCP OAuth credential. + + - `AccessToken string` + + OAuth access token. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthCreateParamsType` + + - `const BetaManagedAgentsMCPOAuthCreateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthCreateParamsType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshParamsResp` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `ClientID string` + + OAuth client ID. + + - `RefreshToken string` + + OAuth refresh token. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnionResp` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerCreateParamsResp struct{…}` + + Parameters for creating a static bearer token credential. + + - `Token string` + + Static bearer token value. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerCreateParamsType` + + - `const BetaManagedAgentsStaticBearerCreateParamsTypeStaticBearer BetaManagedAgentsStaticBearerCreateParamsType = "static_bearer"` + + - `DisplayName param.Field[string]` + + Body param: Human-readable name for the credential. Up to 255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Arbitrary key-value metadata to attach to the credential. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.New( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultCredentialNewParams{ + Auth: anthropic.BetaVaultCredentialNewParamsAuthUnion{ + OfStaticBearer: &anthropic.BetaManagedAgentsStaticBearerCreateParams{ + Token: "bearer_exampletoken", + MCPServerURL: "https://example-server.modelcontextprotocol.io/sse", + Type: anthropic.BetaManagedAgentsStaticBearerCreateParamsTypeStaticBearer, + }, + }, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` + +## List + +`client.Beta.Vaults.Credentials.List(ctx, vaultID, params) (*PageCursor[BetaManagedAgentsCredential], error)` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vaultID string` + +- `params BetaVaultCredentialListParams` + + - `IncludeArchived param.Field[bool]` + + Query param: Whether to include archived credentials in the results. + + - `Limit param.Field[int64]` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination token from a previous `list_credentials` response. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Vaults.Credentials.List( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultCredentialListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` + +## Retrieve + +`client.Beta.Vaults.Credentials.Get(ctx, credentialID, params) (*BetaManagedAgentsCredential, error)` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialGetParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.Get( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialGetParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` + +## Update + +`client.Beta.Vaults.Credentials.Update(ctx, credentialID, params) (*BetaManagedAgentsCredential, error)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialUpdateParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Auth param.Field[BetaVaultCredentialUpdateParamsAuthUnion]` + + Body param: Updated authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthUpdateParamsResp struct{…}` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsMCPOAuthUpdateParamsType` + + - `const BetaManagedAgentsMCPOAuthUpdateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthUpdateParamsType = "mcp_oauth"` + + - `AccessToken string` + + Updated OAuth access token. + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshUpdateParamsResp` + + Parameters for updating OAuth refresh token configuration. + + - `RefreshToken string` + + Updated OAuth refresh token. + + - `Scope string` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshUpdateParamsTokenEndpointAuthUnionResp` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` + + Updated POST body authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsStaticBearerUpdateParamsResp struct{…}` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsStaticBearerUpdateParamsType` + + - `const BetaManagedAgentsStaticBearerUpdateParamsTypeStaticBearer BetaManagedAgentsStaticBearerUpdateParamsType = "static_bearer"` + + - `Token string` + + Updated static bearer token value. + + - `DisplayName param.Field[string]` + + Body param: Updated human-readable name for the credential. 1-255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.Update( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialUpdateParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` + +## Delete + +`client.Beta.Vaults.Credentials.Delete(ctx, credentialID, params) (*BetaManagedAgentsDeletedCredential, error)` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialDeleteParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeletedCredential struct{…}` + + Confirmation of a deleted credential. + + - `ID string` + + Unique identifier of the deleted credential. + + - `Type BetaManagedAgentsDeletedCredentialType` + + - `const BetaManagedAgentsDeletedCredentialTypeVaultCredentialDeleted BetaManagedAgentsDeletedCredentialType = "vault_credential_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeletedCredential, err := client.Beta.Vaults.Credentials.Delete( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialDeleteParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeletedCredential.ID) +} +``` + +## Archive + +`client.Beta.Vaults.Credentials.Archive(ctx, credentialID, params) (*BetaManagedAgentsCredential, error)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialArchiveParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.Archive( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialArchiveParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `type BetaManagedAgentsDeletedCredential struct{…}` + + Confirmation of a deleted credential. + + - `ID string` + + Unique identifier of the deleted credential. + + - `Type BetaManagedAgentsDeletedCredentialType` + + - `const BetaManagedAgentsDeletedCredentialTypeVaultCredentialDeleted BetaManagedAgentsDeletedCredentialType = "vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `type BetaManagedAgentsMCPOAuthCreateParamsResp struct{…}` + + Parameters for creating an MCP OAuth credential. + + - `AccessToken string` + + OAuth access token. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthCreateParamsType` + + - `const BetaManagedAgentsMCPOAuthCreateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthCreateParamsType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshParamsResp` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `ClientID string` + + OAuth client ID. + + - `RefreshToken string` + + OAuth refresh token. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnionResp` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `type BetaManagedAgentsMCPOAuthRefreshParamsResp struct{…}` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `ClientID string` + + OAuth client ID. + + - `RefreshToken string` + + OAuth refresh token. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnionResp` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `type BetaManagedAgentsMCPOAuthRefreshResponse struct{…}` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `type BetaManagedAgentsMCPOAuthRefreshUpdateParamsResp struct{…}` + + Parameters for updating OAuth refresh token configuration. + + - `RefreshToken string` + + Updated OAuth refresh token. + + - `Scope string` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshUpdateParamsTokenEndpointAuthUnionResp` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` + + Updated POST body authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` + + - `ClientSecret string` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `type BetaManagedAgentsMCPOAuthUpdateParamsResp struct{…}` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsMCPOAuthUpdateParamsType` + + - `const BetaManagedAgentsMCPOAuthUpdateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthUpdateParamsType = "mcp_oauth"` + + - `AccessToken string` + + Updated OAuth access token. + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshUpdateParamsResp` + + Parameters for updating OAuth refresh token configuration. + + - `RefreshToken string` + + Updated OAuth refresh token. + + - `Scope string` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshUpdateParamsTokenEndpointAuthUnionResp` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` + + Updated POST body authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` + + - `ClientSecret string` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `type BetaManagedAgentsStaticBearerCreateParamsResp struct{…}` + + Parameters for creating a static bearer token credential. + + - `Token string` + + Static bearer token value. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerCreateParamsType` + + - `const BetaManagedAgentsStaticBearerCreateParamsTypeStaticBearer BetaManagedAgentsStaticBearerCreateParamsType = "static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `type BetaManagedAgentsStaticBearerUpdateParamsResp struct{…}` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsStaticBearerUpdateParamsType` + + - `const BetaManagedAgentsStaticBearerUpdateParamsTypeStaticBearer BetaManagedAgentsStaticBearerUpdateParamsType = "static_bearer"` + + - `Token string` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` + + - `ClientSecret string` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` + + Updated POST body authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` + + - `ClientSecret string` + + Updated OAuth client secret. diff --git a/content/en/api/go/beta/vaults/credentials/archive.md b/content/en/api/go/beta/vaults/credentials/archive.md new file mode 100644 index 000000000..4313e56f3 --- /dev/null +++ b/content/en/api/go/beta/vaults/credentials/archive.md @@ -0,0 +1,216 @@ +## Archive + +`client.Beta.Vaults.Credentials.Archive(ctx, credentialID, params) (*BetaManagedAgentsCredential, error)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialArchiveParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.Archive( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialArchiveParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` diff --git a/content/en/api/go/beta/vaults/credentials/create.md b/content/en/api/go/beta/vaults/credentials/create.md new file mode 100644 index 000000000..a0c99be2f --- /dev/null +++ b/content/en/api/go/beta/vaults/credentials/create.md @@ -0,0 +1,326 @@ +## Create + +`client.Beta.Vaults.Credentials.New(ctx, vaultID, params) (*BetaManagedAgentsCredential, error)` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vaultID string` + +- `params BetaVaultCredentialNewParams` + + - `Auth param.Field[BetaVaultCredentialNewParamsAuthUnion]` + + Body param: Authentication details for creating a credential. + + - `type BetaManagedAgentsMCPOAuthCreateParamsResp struct{…}` + + Parameters for creating an MCP OAuth credential. + + - `AccessToken string` + + OAuth access token. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthCreateParamsType` + + - `const BetaManagedAgentsMCPOAuthCreateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthCreateParamsType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshParamsResp` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `ClientID string` + + OAuth client ID. + + - `RefreshToken string` + + OAuth refresh token. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnionResp` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneParamResp struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneParamType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneParamTypeNone BetaManagedAgentsTokenEndpointAuthNoneParamType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicParamResp struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicParamType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostParamResp struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `ClientSecret string` + + OAuth client secret. + + - `Type BetaManagedAgentsTokenEndpointAuthPostParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostParamType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerCreateParamsResp struct{…}` + + Parameters for creating a static bearer token credential. + + - `Token string` + + Static bearer token value. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerCreateParamsType` + + - `const BetaManagedAgentsStaticBearerCreateParamsTypeStaticBearer BetaManagedAgentsStaticBearerCreateParamsType = "static_bearer"` + + - `DisplayName param.Field[string]` + + Body param: Human-readable name for the credential. Up to 255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Arbitrary key-value metadata to attach to the credential. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.New( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultCredentialNewParams{ + Auth: anthropic.BetaVaultCredentialNewParamsAuthUnion{ + OfStaticBearer: &anthropic.BetaManagedAgentsStaticBearerCreateParams{ + Token: "bearer_exampletoken", + MCPServerURL: "https://example-server.modelcontextprotocol.io/sse", + Type: anthropic.BetaManagedAgentsStaticBearerCreateParamsTypeStaticBearer, + }, + }, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` diff --git a/content/en/api/go/beta/vaults/credentials/delete.md b/content/en/api/go/beta/vaults/credentials/delete.md new file mode 100644 index 000000000..4c1e8d77e --- /dev/null +++ b/content/en/api/go/beta/vaults/credentials/delete.md @@ -0,0 +1,112 @@ +## Delete + +`client.Beta.Vaults.Credentials.Delete(ctx, credentialID, params) (*BetaManagedAgentsDeletedCredential, error)` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialDeleteParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeletedCredential struct{…}` + + Confirmation of a deleted credential. + + - `ID string` + + Unique identifier of the deleted credential. + + - `Type BetaManagedAgentsDeletedCredentialType` + + - `const BetaManagedAgentsDeletedCredentialTypeVaultCredentialDeleted BetaManagedAgentsDeletedCredentialType = "vault_credential_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeletedCredential, err := client.Beta.Vaults.Credentials.Delete( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialDeleteParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeletedCredential.ID) +} +``` diff --git a/content/en/api/go/beta/vaults/credentials/list.md b/content/en/api/go/beta/vaults/credentials/list.md new file mode 100644 index 000000000..45dc04b75 --- /dev/null +++ b/content/en/api/go/beta/vaults/credentials/list.md @@ -0,0 +1,224 @@ +## List + +`client.Beta.Vaults.Credentials.List(ctx, vaultID, params) (*PageCursor[BetaManagedAgentsCredential], error)` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vaultID string` + +- `params BetaVaultCredentialListParams` + + - `IncludeArchived param.Field[bool]` + + Query param: Whether to include archived credentials in the results. + + - `Limit param.Field[int64]` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination token from a previous `list_credentials` response. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Vaults.Credentials.List( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultCredentialListParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` diff --git a/content/en/api/go/beta/vaults/credentials/retrieve.md b/content/en/api/go/beta/vaults/credentials/retrieve.md new file mode 100644 index 000000000..692960166 --- /dev/null +++ b/content/en/api/go/beta/vaults/credentials/retrieve.md @@ -0,0 +1,216 @@ +## Retrieve + +`client.Beta.Vaults.Credentials.Get(ctx, credentialID, params) (*BetaManagedAgentsCredential, error)` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialGetParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.Get( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialGetParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` diff --git a/content/en/api/go/beta/vaults/credentials/update.md b/content/en/api/go/beta/vaults/credentials/update.md new file mode 100644 index 000000000..f339785ff --- /dev/null +++ b/content/en/api/go/beta/vaults/credentials/update.md @@ -0,0 +1,296 @@ +## Update + +`client.Beta.Vaults.Credentials.Update(ctx, credentialID, params) (*BetaManagedAgentsCredential, error)` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `credentialID string` + +- `params BetaVaultCredentialUpdateParams` + + - `VaultID param.Field[string]` + + Path param: Path parameter vault_id + + - `Auth param.Field[BetaVaultCredentialUpdateParamsAuthUnion]` + + Body param: Updated authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthUpdateParamsResp struct{…}` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsMCPOAuthUpdateParamsType` + + - `const BetaManagedAgentsMCPOAuthUpdateParamsTypeMCPOAuth BetaManagedAgentsMCPOAuthUpdateParamsType = "mcp_oauth"` + + - `AccessToken string` + + Updated OAuth access token. + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshUpdateParamsResp` + + Parameters for updating OAuth refresh token configuration. + + - `RefreshToken string` + + Updated OAuth refresh token. + + - `Scope string` + + Updated OAuth scope for the refresh request. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshUpdateParamsTokenEndpointAuthUnionResp` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamResp struct{…}` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicUpdateParamTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicUpdateParamType = "client_secret_basic"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsTokenEndpointAuthPostUpdateParamResp struct{…}` + + Updated POST body authentication parameters for the token endpoint. + + - `Type BetaManagedAgentsTokenEndpointAuthPostUpdateParamType` + + - `const BetaManagedAgentsTokenEndpointAuthPostUpdateParamTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostUpdateParamType = "client_secret_post"` + + - `ClientSecret string` + + Updated OAuth client secret. + + - `type BetaManagedAgentsStaticBearerUpdateParamsResp struct{…}` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `Type BetaManagedAgentsStaticBearerUpdateParamsType` + + - `const BetaManagedAgentsStaticBearerUpdateParamsTypeStaticBearer BetaManagedAgentsStaticBearerUpdateParamsType = "static_bearer"` + + - `Token string` + + Updated static bearer token value. + + - `DisplayName param.Field[string]` + + Body param: Updated human-readable name for the credential. 1-255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsCredential struct{…}` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `ID string` + + Unique identifier for the credential. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `Auth BetaManagedAgentsCredentialAuthUnion` + + Authentication details for a credential. + + - `type BetaManagedAgentsMCPOAuthAuthResponse struct{…}` + + OAuth credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsMCPOAuthAuthResponseType` + + - `const BetaManagedAgentsMCPOAuthAuthResponseTypeMCPOAuth BetaManagedAgentsMCPOAuthAuthResponseType = "mcp_oauth"` + + - `ExpiresAt Time` + + A timestamp in RFC 3339 format + + - `Refresh BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `ClientID string` + + OAuth client ID. + + - `TokenEndpoint string` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth BetaManagedAgentsMCPOAuthRefreshResponseTokenEndpointAuthUnion` + + Token endpoint requires no client authentication. + + - `type BetaManagedAgentsTokenEndpointAuthNoneResponse struct{…}` + + Token endpoint requires no client authentication. + + - `Type BetaManagedAgentsTokenEndpointAuthNoneResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthNoneResponseTypeNone BetaManagedAgentsTokenEndpointAuthNoneResponseType = "none"` + + - `type BetaManagedAgentsTokenEndpointAuthBasicResponse struct{…}` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthBasicResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthBasicResponseTypeClientSecretBasic BetaManagedAgentsTokenEndpointAuthBasicResponseType = "client_secret_basic"` + + - `type BetaManagedAgentsTokenEndpointAuthPostResponse struct{…}` + + Token endpoint uses POST body authentication with client credentials. + + - `Type BetaManagedAgentsTokenEndpointAuthPostResponseType` + + - `const BetaManagedAgentsTokenEndpointAuthPostResponseTypeClientSecretPost BetaManagedAgentsTokenEndpointAuthPostResponseType = "client_secret_post"` + + - `Resource string` + + OAuth resource indicator. + + - `Scope string` + + OAuth scope for the refresh request. + + - `type BetaManagedAgentsStaticBearerAuthResponse struct{…}` + + Static bearer token credential details for an MCP server. + + - `MCPServerURL string` + + URL of the MCP server this credential authenticates against. + + - `Type BetaManagedAgentsStaticBearerAuthResponseType` + + - `const BetaManagedAgentsStaticBearerAuthResponseTypeStaticBearer BetaManagedAgentsStaticBearerAuthResponseType = "static_bearer"` + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the credential. + + - `Type BetaManagedAgentsCredentialType` + + - `const BetaManagedAgentsCredentialTypeVaultCredential BetaManagedAgentsCredentialType = "vault_credential"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + + - `VaultID string` + + Identifier of the vault this credential belongs to. + + - `DisplayName string` + + Human-readable name for the credential. + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsCredential, err := client.Beta.Vaults.Credentials.Update( + context.TODO(), + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + anthropic.BetaVaultCredentialUpdateParams{ + VaultID: "vlt_011CZkZDLs7fYzm1hXNPeRjv", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsCredential.ID) +} +``` diff --git a/content/en/api/go/beta/vaults/delete.md b/content/en/api/go/beta/vaults/delete.md new file mode 100644 index 000000000..f67048e36 --- /dev/null +++ b/content/en/api/go/beta/vaults/delete.md @@ -0,0 +1,108 @@ +## Delete + +`client.Beta.Vaults.Delete(ctx, vaultID, body) (*BetaManagedAgentsDeletedVault, error)` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `vaultID string` + +- `body BetaVaultDeleteParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsDeletedVault struct{…}` + + Confirmation of a deleted vault. + + - `ID string` + + Unique identifier of the deleted vault. + + - `Type BetaManagedAgentsDeletedVaultType` + + - `const BetaManagedAgentsDeletedVaultTypeVaultDeleted BetaManagedAgentsDeletedVaultType = "vault_deleted"` + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsDeletedVault, err := client.Beta.Vaults.Delete( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultDeleteParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsDeletedVault.ID) +} +``` diff --git a/content/en/api/go/beta/vaults/list.md b/content/en/api/go/beta/vaults/list.md new file mode 100644 index 000000000..b5e5595a2 --- /dev/null +++ b/content/en/api/go/beta/vaults/list.md @@ -0,0 +1,134 @@ +## List + +`client.Beta.Vaults.List(ctx, params) (*PageCursor[BetaManagedAgentsVault], error)` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `params BetaVaultListParams` + + - `IncludeArchived param.Field[bool]` + + Query param: Whether to include archived vaults in the results. + + - `Limit param.Field[int64]` + + Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. + + - `Page param.Field[string]` + + Query param: Opaque pagination token from a previous `list_vaults` response. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + page, err := client.Beta.Vaults.List(context.TODO(), anthropic.BetaVaultListParams{ + + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) +} +``` diff --git a/content/en/api/go/beta/vaults/retrieve.md b/content/en/api/go/beta/vaults/retrieve.md new file mode 100644 index 000000000..422ab443b --- /dev/null +++ b/content/en/api/go/beta/vaults/retrieve.md @@ -0,0 +1,128 @@ +## Retrieve + +`client.Beta.Vaults.Get(ctx, vaultID, query) (*BetaManagedAgentsVault, error)` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `vaultID string` + +- `query BetaVaultGetParams` + + - `Betas param.Field[[]AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsVault, err := client.Beta.Vaults.Get( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultGetParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsVault.ID) +} +``` diff --git a/content/en/api/go/beta/vaults/update.md b/content/en/api/go/beta/vaults/update.md new file mode 100644 index 000000000..c76a8384e --- /dev/null +++ b/content/en/api/go/beta/vaults/update.md @@ -0,0 +1,136 @@ +## Update + +`client.Beta.Vaults.Update(ctx, vaultID, params) (*BetaManagedAgentsVault, error)` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `vaultID string` + +- `params BetaVaultUpdateParams` + + - `DisplayName param.Field[string]` + + Body param: Updated human-readable name for the vault. 1-255 characters. + + - `Metadata param.Field[map[string, string]]` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `Betas param.Field[[]AnthropicBeta]` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `string` + + - `type AnthropicBeta string` + + - `const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"` + + - `const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"` + + - `const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"` + + - `const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"` + + - `const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"` + + - `const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"` + + - `const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"` + + - `const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"` + + - `const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"` + + - `const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"` + + - `const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"` + + - `const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"` + + - `const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"` + + - `const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"` + + - `const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"` + + - `const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"` + + - `const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"` + + - `const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"` + + - `const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"` + + - `const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"` + + - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` + +### Returns + +- `type BetaManagedAgentsVault struct{…}` + + A vault that stores credentials for use by agents during sessions. + + - `ID string` + + Unique identifier for the vault. + + - `ArchivedAt Time` + + A timestamp in RFC 3339 format + + - `CreatedAt Time` + + A timestamp in RFC 3339 format + + - `DisplayName string` + + Human-readable name for the vault. + + - `Metadata map[string, string]` + + Arbitrary key-value metadata attached to the vault. + + - `Type BetaManagedAgentsVaultType` + + - `const BetaManagedAgentsVaultTypeVault BetaManagedAgentsVaultType = "vault"` + + - `UpdatedAt Time` + + A timestamp in RFC 3339 format + +### Example + +```go +package main + +import ( + "context" + "fmt" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +func main() { + client := anthropic.NewClient( + option.WithAPIKey("my-anthropic-api-key"), + ) + betaManagedAgentsVault, err := client.Beta.Vaults.Update( + context.TODO(), + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + anthropic.BetaVaultUpdateParams{ + + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", betaManagedAgentsVault.ID) +} +``` diff --git a/content/en/api/go/completions.md b/content/en/api/go/completions.md index 2fb67476d..056e0fdff 100644 --- a/content/en/api/go/completions.md +++ b/content/en/api/go/completions.md @@ -136,8 +136,6 @@ Future models and features will not be compatible with Text Completions. See our - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type Completion struct{…}` @@ -164,9 +162,13 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -262,7 +264,7 @@ func main() { ) completion, err := client.Completions.New(context.TODO(), anthropic.CompletionNewParams{ MaxTokensToSample: 256, - Model: anthropic.ModelClaudeOpus4_6, + Model: anthropic.ModelClaudeMythosPreview, Prompt: "\n\nHuman: Hello, world!\n\nAssistant:", }) if err != nil { @@ -300,9 +302,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` diff --git a/content/en/api/go/completions/create.md b/content/en/api/go/completions/create.md index 45ff14c51..607645b64 100644 --- a/content/en/api/go/completions/create.md +++ b/content/en/api/go/completions/create.md @@ -134,8 +134,6 @@ Future models and features will not be compatible with Text Completions. See our - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type Completion struct{…}` @@ -162,9 +160,13 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -260,7 +262,7 @@ func main() { ) completion, err := client.Completions.New(context.TODO(), anthropic.CompletionNewParams{ MaxTokensToSample: 256, - Model: anthropic.ModelClaudeOpus4_6, + Model: anthropic.ModelClaudeMythosPreview, Prompt: "\n\nHuman: Hello, world!\n\nAssistant:", }) if err != nil { diff --git a/content/en/api/go/messages.md b/content/en/api/go/messages.md index 27c60ff3f..1fb4a1480 100644 --- a/content/en/api/go/messages.md +++ b/content/en/api/go/messages.md @@ -4317,9 +4317,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -8124,7 +8128,7 @@ func main() { }}, Role: anthropic.MessageParamRoleUser, }}, - Model: anthropic.ModelClaudeOpus4_6, + Model: anthropic.ModelClaudeMythosPreview, }) if err != nil { panic(err.Error()) @@ -13827,9 +13831,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -17360,9 +17368,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -19235,9 +19247,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -20171,9 +20187,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -29262,9 +29282,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -32122,9 +32146,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -33406,9 +33434,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -34470,9 +34502,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -35496,9 +35532,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` diff --git a/content/en/api/go/messages/batches.md b/content/en/api/go/messages/batches.md index 85c72d7b1..0a2ccea6b 100644 --- a/content/en/api/go/messages/batches.md +++ b/content/en/api/go/messages/batches.md @@ -2325,9 +2325,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -5185,9 +5189,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -6469,9 +6477,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -7533,9 +7545,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` @@ -8559,9 +8575,13 @@ func main() { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` diff --git a/content/en/api/go/messages/batches/create.md b/content/en/api/go/messages/batches/create.md index 9fd501e38..903a71a49 100644 --- a/content/en/api/go/messages/batches/create.md +++ b/content/en/api/go/messages/batches/create.md @@ -2323,9 +2323,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` diff --git a/content/en/api/go/messages/batches/results.md b/content/en/api/go/messages/batches/results.md index 95cf9c913..22e2a9ef3 100644 --- a/content/en/api/go/messages/batches/results.md +++ b/content/en/api/go/messages/batches/results.md @@ -753,9 +753,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` diff --git a/content/en/api/go/messages/count_tokens.md b/content/en/api/go/messages/count_tokens.md index f507ab298..75e913cac 100644 --- a/content/en/api/go/messages/count_tokens.md +++ b/content/en/api/go/messages/count_tokens.md @@ -3568,7 +3568,7 @@ func main() { }}, Role: anthropic.MessageParamRoleUser, }}, - Model: anthropic.ModelClaudeOpus4_6, + Model: anthropic.ModelClaudeMythosPreview, }) if err != nil { panic(err.Error()) diff --git a/content/en/api/go/messages/create.md b/content/en/api/go/messages/create.md index ac2aafb22..129ac7281 100644 --- a/content/en/api/go/messages/create.md +++ b/content/en/api/go/messages/create.md @@ -4315,9 +4315,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `const ModelClaudeMythosPreview Model = "claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `const ModelClaudeOpus4_6 Model = "claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `const ModelClaudeSonnet4_6 Model = "claude-sonnet-4-6"` diff --git a/content/en/api/go/models.md b/content/en/api/go/models.md index e50e746fc..c328a3259 100644 --- a/content/en/api/go/models.md +++ b/content/en/api/go/models.md @@ -78,8 +78,6 @@ The Models API response can be used to determine which models are available for - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type ModelInfo struct{…}` @@ -359,8 +357,6 @@ The Models API response can be used to determine information about a specific mo - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type ModelInfo struct{…}` diff --git a/content/en/api/go/models/list.md b/content/en/api/go/models/list.md index 44b5ed586..0a4dc7441 100644 --- a/content/en/api/go/models/list.md +++ b/content/en/api/go/models/list.md @@ -76,8 +76,6 @@ The Models API response can be used to determine which models are available for - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type ModelInfo struct{…}` diff --git a/content/en/api/go/models/retrieve.md b/content/en/api/go/models/retrieve.md index df7ec9820..a6a8b6346 100644 --- a/content/en/api/go/models/retrieve.md +++ b/content/en/api/go/models/retrieve.md @@ -66,8 +66,6 @@ The Models API response can be used to determine information about a specific mo - `const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"` - - `const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"` - ### Returns - `type ModelInfo struct{…}` diff --git a/content/en/api/java/beta.md b/content/en/api/java/beta.md index 005ce79dd..5047069a1 100644 --- a/content/en/api/java/beta.md +++ b/content/en/api/java/beta.md @@ -1,46814 +1 @@ -# Beta - -## Domain Types - -### Beta API Error - -- `class BetaApiError:` - - - `String message` - - - `JsonValue; type "api_error"constant` - - - `API_ERROR("api_error")` - -### Beta Authentication Error - -- `class BetaAuthenticationError:` - - - `String message` - - - `JsonValue; type "authentication_error"constant` - - - `AUTHENTICATION_ERROR("authentication_error")` - -### Beta Billing Error - -- `class BetaBillingError:` - - - `String message` - - - `JsonValue; type "billing_error"constant` - - - `BILLING_ERROR("billing_error")` - -### Beta Error - -- `class BetaError: A class that can be one of several variants.union` - - - `class BetaInvalidRequestError:` - - - `String message` - - - `JsonValue; type "invalid_request_error"constant` - - - `INVALID_REQUEST_ERROR("invalid_request_error")` - - - `class BetaAuthenticationError:` - - - `String message` - - - `JsonValue; type "authentication_error"constant` - - - `AUTHENTICATION_ERROR("authentication_error")` - - - `class BetaBillingError:` - - - `String message` - - - `JsonValue; type "billing_error"constant` - - - `BILLING_ERROR("billing_error")` - - - `class BetaPermissionError:` - - - `String message` - - - `JsonValue; type "permission_error"constant` - - - `PERMISSION_ERROR("permission_error")` - - - `class BetaNotFoundError:` - - - `String message` - - - `JsonValue; type "not_found_error"constant` - - - `NOT_FOUND_ERROR("not_found_error")` - - - `class BetaRateLimitError:` - - - `String message` - - - `JsonValue; type "rate_limit_error"constant` - - - `RATE_LIMIT_ERROR("rate_limit_error")` - - - `class BetaGatewayTimeoutError:` - - - `String message` - - - `JsonValue; type "timeout_error"constant` - - - `TIMEOUT_ERROR("timeout_error")` - - - `class BetaApiError:` - - - `String message` - - - `JsonValue; type "api_error"constant` - - - `API_ERROR("api_error")` - - - `class BetaOverloadedError:` - - - `String message` - - - `JsonValue; type "overloaded_error"constant` - - - `OVERLOADED_ERROR("overloaded_error")` - -### Beta Error Response - -- `class BetaErrorResponse:` - - - `BetaError error` - - - `class BetaInvalidRequestError:` - - - `String message` - - - `JsonValue; type "invalid_request_error"constant` - - - `INVALID_REQUEST_ERROR("invalid_request_error")` - - - `class BetaAuthenticationError:` - - - `String message` - - - `JsonValue; type "authentication_error"constant` - - - `AUTHENTICATION_ERROR("authentication_error")` - - - `class BetaBillingError:` - - - `String message` - - - `JsonValue; type "billing_error"constant` - - - `BILLING_ERROR("billing_error")` - - - `class BetaPermissionError:` - - - `String message` - - - `JsonValue; type "permission_error"constant` - - - `PERMISSION_ERROR("permission_error")` - - - `class BetaNotFoundError:` - - - `String message` - - - `JsonValue; type "not_found_error"constant` - - - `NOT_FOUND_ERROR("not_found_error")` - - - `class BetaRateLimitError:` - - - `String message` - - - `JsonValue; type "rate_limit_error"constant` - - - `RATE_LIMIT_ERROR("rate_limit_error")` - - - `class BetaGatewayTimeoutError:` - - - `String message` - - - `JsonValue; type "timeout_error"constant` - - - `TIMEOUT_ERROR("timeout_error")` - - - `class BetaApiError:` - - - `String message` - - - `JsonValue; type "api_error"constant` - - - `API_ERROR("api_error")` - - - `class BetaOverloadedError:` - - - `String message` - - - `JsonValue; type "overloaded_error"constant` - - - `OVERLOADED_ERROR("overloaded_error")` - - - `Optional requestId` - - - `JsonValue; type "error"constant` - - - `ERROR("error")` - -### Beta Gateway Timeout Error - -- `class BetaGatewayTimeoutError:` - - - `String message` - - - `JsonValue; type "timeout_error"constant` - - - `TIMEOUT_ERROR("timeout_error")` - -### Beta Invalid Request Error - -- `class BetaInvalidRequestError:` - - - `String message` - - - `JsonValue; type "invalid_request_error"constant` - - - `INVALID_REQUEST_ERROR("invalid_request_error")` - -### Beta Not Found Error - -- `class BetaNotFoundError:` - - - `String message` - - - `JsonValue; type "not_found_error"constant` - - - `NOT_FOUND_ERROR("not_found_error")` - -### Beta Overloaded Error - -- `class BetaOverloadedError:` - - - `String message` - - - `JsonValue; type "overloaded_error"constant` - - - `OVERLOADED_ERROR("overloaded_error")` - -### Beta Permission Error - -- `class BetaPermissionError:` - - - `String message` - - - `JsonValue; type "permission_error"constant` - - - `PERMISSION_ERROR("permission_error")` - -### Beta Rate Limit Error - -- `class BetaRateLimitError:` - - - `String message` - - - `JsonValue; type "rate_limit_error"constant` - - - `RATE_LIMIT_ERROR("rate_limit_error")` - -# Models - -## List - -`ModelListPage beta().models().list(ModelListParamsparams = ModelListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/models` - -List available models. - -The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first. - -### Parameters - -- `ModelListParams params` - - - `Optional afterId` - - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - - - `Optional beforeId` - - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - - - `Optional limit` - - Number of items to return per page. - - Defaults to `20`. Ranges from `1` to `1000`. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class BetaModelInfo:` - - - `String id` - - Unique model identifier. - - - `Optional capabilities` - - Model capability information. - - - `BetaCapabilitySupport batch` - - Whether the model supports the Batch API. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport citations` - - Whether the model supports citation generation. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport codeExecution` - - Whether the model supports code execution tools. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaContextManagementCapability contextManagement` - - Context management support and available strategies. - - - `Optional clearThinking20251015` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `Optional clearToolUses20250919` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `Optional compact20260112` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaEffortCapability effort` - - Effort (reasoning_effort) support and available levels. - - - `BetaCapabilitySupport high` - - Whether the model supports high effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport low` - - Whether the model supports low effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport max` - - Whether the model supports max effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport medium` - - Whether the model supports medium effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport imageInput` - - Whether the model accepts image content blocks. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport pdfInput` - - Whether the model accepts PDF content blocks. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport structuredOutputs` - - Whether the model supports structured output / JSON mode / strict tool schemas. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaThinkingCapability thinking` - - Thinking capability and supported type configurations. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaThinkingTypes types` - - Supported thinking type configurations. - - - `BetaCapabilitySupport adaptive` - - Whether the model supports thinking with type 'adaptive' (auto). - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport enabled` - - Whether the model supports thinking with type 'enabled'. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `LocalDateTime createdAt` - - RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. - - - `String displayName` - - A human-readable name for the model. - - - `Optional maxInputTokens` - - Maximum input context window size in tokens for this model. - - - `Optional maxTokens` - - Maximum value for the `max_tokens` parameter when using this model. - - - `JsonValue; type "model"constant` - - Object type. - - For Models, this is always `"model"`. - - - `MODEL("model")` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.models.ModelListPage; -import com.anthropic.models.beta.models.ModelListParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - ModelListPage page = client.beta().models().list(); - } -} -``` - -## Retrieve - -`BetaModelInfo beta().models().retrieve(ModelRetrieveParamsparams = ModelRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/models/{model_id}` - -Get a specific model. - -The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID. - -### Parameters - -- `ModelRetrieveParams params` - - - `Optional modelId` - - Model identifier or alias. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class BetaModelInfo:` - - - `String id` - - Unique model identifier. - - - `Optional capabilities` - - Model capability information. - - - `BetaCapabilitySupport batch` - - Whether the model supports the Batch API. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport citations` - - Whether the model supports citation generation. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport codeExecution` - - Whether the model supports code execution tools. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaContextManagementCapability contextManagement` - - Context management support and available strategies. - - - `Optional clearThinking20251015` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `Optional clearToolUses20250919` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `Optional compact20260112` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaEffortCapability effort` - - Effort (reasoning_effort) support and available levels. - - - `BetaCapabilitySupport high` - - Whether the model supports high effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport low` - - Whether the model supports low effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport max` - - Whether the model supports max effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport medium` - - Whether the model supports medium effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport imageInput` - - Whether the model accepts image content blocks. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport pdfInput` - - Whether the model accepts PDF content blocks. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport structuredOutputs` - - Whether the model supports structured output / JSON mode / strict tool schemas. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaThinkingCapability thinking` - - Thinking capability and supported type configurations. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaThinkingTypes types` - - Supported thinking type configurations. - - - `BetaCapabilitySupport adaptive` - - Whether the model supports thinking with type 'adaptive' (auto). - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport enabled` - - Whether the model supports thinking with type 'enabled'. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `LocalDateTime createdAt` - - RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. - - - `String displayName` - - A human-readable name for the model. - - - `Optional maxInputTokens` - - Maximum input context window size in tokens for this model. - - - `Optional maxTokens` - - Maximum value for the `max_tokens` parameter when using this model. - - - `JsonValue; type "model"constant` - - Object type. - - For Models, this is always `"model"`. - - - `MODEL("model")` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.models.BetaModelInfo; -import com.anthropic.models.beta.models.ModelRetrieveParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - BetaModelInfo betaModelInfo = client.beta().models().retrieve("model_id"); - } -} -``` - -## Domain Types - -### Beta Capability Support - -- `class BetaCapabilitySupport:` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - -### Beta Context Management Capability - -- `class BetaContextManagementCapability:` - - Context management capability details. - - - `Optional clearThinking20251015` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `Optional clearToolUses20250919` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `Optional compact20260112` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `boolean supported` - - Whether this capability is supported by the model. - -### Beta Effort Capability - -- `class BetaEffortCapability:` - - Effort (reasoning_effort) capability details. - - - `BetaCapabilitySupport high` - - Whether the model supports high effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport low` - - Whether the model supports low effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport max` - - Whether the model supports max effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport medium` - - Whether the model supports medium effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `boolean supported` - - Whether this capability is supported by the model. - -### Beta Model Capabilities - -- `class BetaModelCapabilities:` - - Model capability information. - - - `BetaCapabilitySupport batch` - - Whether the model supports the Batch API. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport citations` - - Whether the model supports citation generation. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport codeExecution` - - Whether the model supports code execution tools. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaContextManagementCapability contextManagement` - - Context management support and available strategies. - - - `Optional clearThinking20251015` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `Optional clearToolUses20250919` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `Optional compact20260112` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaEffortCapability effort` - - Effort (reasoning_effort) support and available levels. - - - `BetaCapabilitySupport high` - - Whether the model supports high effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport low` - - Whether the model supports low effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport max` - - Whether the model supports max effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport medium` - - Whether the model supports medium effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport imageInput` - - Whether the model accepts image content blocks. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport pdfInput` - - Whether the model accepts PDF content blocks. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport structuredOutputs` - - Whether the model supports structured output / JSON mode / strict tool schemas. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaThinkingCapability thinking` - - Thinking capability and supported type configurations. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaThinkingTypes types` - - Supported thinking type configurations. - - - `BetaCapabilitySupport adaptive` - - Whether the model supports thinking with type 'adaptive' (auto). - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport enabled` - - Whether the model supports thinking with type 'enabled'. - - - `boolean supported` - - Whether this capability is supported by the model. - -### Beta Model Info - -- `class BetaModelInfo:` - - - `String id` - - Unique model identifier. - - - `Optional capabilities` - - Model capability information. - - - `BetaCapabilitySupport batch` - - Whether the model supports the Batch API. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport citations` - - Whether the model supports citation generation. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport codeExecution` - - Whether the model supports code execution tools. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaContextManagementCapability contextManagement` - - Context management support and available strategies. - - - `Optional clearThinking20251015` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `Optional clearToolUses20250919` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `Optional compact20260112` - - Indicates whether a capability is supported. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaEffortCapability effort` - - Effort (reasoning_effort) support and available levels. - - - `BetaCapabilitySupport high` - - Whether the model supports high effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport low` - - Whether the model supports low effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport max` - - Whether the model supports max effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport medium` - - Whether the model supports medium effort level. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport imageInput` - - Whether the model accepts image content blocks. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport pdfInput` - - Whether the model accepts PDF content blocks. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport structuredOutputs` - - Whether the model supports structured output / JSON mode / strict tool schemas. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaThinkingCapability thinking` - - Thinking capability and supported type configurations. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaThinkingTypes types` - - Supported thinking type configurations. - - - `BetaCapabilitySupport adaptive` - - Whether the model supports thinking with type 'adaptive' (auto). - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport enabled` - - Whether the model supports thinking with type 'enabled'. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `LocalDateTime createdAt` - - RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. - - - `String displayName` - - A human-readable name for the model. - - - `Optional maxInputTokens` - - Maximum input context window size in tokens for this model. - - - `Optional maxTokens` - - Maximum value for the `max_tokens` parameter when using this model. - - - `JsonValue; type "model"constant` - - Object type. - - For Models, this is always `"model"`. - - - `MODEL("model")` - -### Beta Thinking Capability - -- `class BetaThinkingCapability:` - - Thinking capability details. - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaThinkingTypes types` - - Supported thinking type configurations. - - - `BetaCapabilitySupport adaptive` - - Whether the model supports thinking with type 'adaptive' (auto). - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport enabled` - - Whether the model supports thinking with type 'enabled'. - - - `boolean supported` - - Whether this capability is supported by the model. - -### Beta Thinking Types - -- `class BetaThinkingTypes:` - - Supported thinking type configurations. - - - `BetaCapabilitySupport adaptive` - - Whether the model supports thinking with type 'adaptive' (auto). - - - `boolean supported` - - Whether this capability is supported by the model. - - - `BetaCapabilitySupport enabled` - - Whether the model supports thinking with type 'enabled'. - - - `boolean supported` - - Whether this capability is supported by the model. - -# Messages - -## Create - -`BetaMessage beta().messages().create(MessageCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - -**post** `/v1/messages` - -Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. - -The Messages API can be used for either single queries or stateless multi-turn conversations. - -Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup) - -### Parameters - -- `MessageCreateParams params` - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - - `long maxTokens` - - The maximum number of tokens to generate before stopping. - - Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. - - Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. - - - `List messages` - - Input messages. - - Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. - - Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. - - If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. - - Example with a single `user` message: - - ```json - [{"role": "user", "content": "Hello, Claude"}] - ``` - - Example with multiple conversational turns: - - ```json - [ - {"role": "user", "content": "Hello there."}, - {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, - {"role": "user", "content": "Can you explain LLMs in plain English?"}, - ] - ``` - - Example with a partially-filled response from Claude: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("}, - ] - ``` - - Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: - - ```json - {"role": "user", "content": "Hello, Claude"} - ``` - - ```json - {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} - ``` - - See [input examples](https://docs.claude.com/en/api/messages-examples). - - Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. - - There is a limit of 100,000 messages in a single request. - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaRequestDocumentBlock:` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `class BetaSearchResultBlockParam:` - - - `List content` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String source` - - - `String title` - - - `JsonValue; type "search_result"constant` - - - `SEARCH_RESULT("search_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `class BetaThinkingBlockParam:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlockParam:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaToolResultBlockParam:` - - - `String toolUseId` - - - `JsonValue; type "tool_result"constant` - - - `TOOL_RESULT("tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaSearchResultBlockParam:` - - - `List content` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String source` - - - `String title` - - - `JsonValue; type "search_result"constant` - - - `SEARCH_RESULT("search_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `class BetaRequestDocumentBlock:` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `class BetaToolReferenceBlockParam:` - - Tool reference block that can be included in tool_result content. - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional isError` - - - `class BetaServerToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlockParam:` - - - `BetaWebSearchToolResultBlockParamContent content` - - - `List` - - - `String encryptedContent` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `Optional pageAge` - - - `class BetaWebSearchToolRequestError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlockParam:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlockParam:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlockParam:` - - - `BetaRequestDocumentBlock content` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlockParam:` - - - `BetaCodeExecutionToolResultBlockParamContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultErrorParam:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlockParam:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaBashCodeExecutionToolResultBlockParam:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaTextEditorCodeExecutionToolResultBlockParam:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `Optional errorMessage` - - - `class BetaTextEditorCodeExecutionViewResultBlockParam:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `class BetaTextEditorCodeExecutionCreateResultBlockParam:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaToolSearchToolResultBlockParam:` - - - `Content content` - - - `class BetaToolSearchToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlockParam:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaMcpToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `String name` - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaRequestMcpToolResultBlockParam:` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional content` - - - `String` - - - `List` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `Optional isError` - - - `class BetaContainerUploadBlockParam:` - - A content block that represents a file to be uploaded to the container - Files uploaded via this block will be available in the container's input directory. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaCompactionBlockParam:` - - A compaction block containing summary of previous context. - - Users should round-trip these blocks from responses to subsequent requests - to maintain context across compaction boundaries. - - When content is None, the block represents a failed compaction. The server - treats these as no-ops. Empty string content is not allowed. - - - `Optional content` - - Summary of previously compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Role role` - - - `USER("user")` - - - `ASSISTANT("assistant")` - - - `Model model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `Optional cacheControl` - - Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - - - `Optional container` - - Container identifier for reuse across requests. - - - `class BetaContainerParams:` - - Container parameters with skills to be loaded. - - - `Optional id` - - Container id - - - `Optional> skills` - - List of skills to load in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `Optional version` - - Skill version or 'latest' for most recent version - - - `String` - - - `Optional contextManagement` - - Context management configuration. - - This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. - - - `Optional inferenceGeo` - - Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. - - - `Optional> mcpServers` - - MCP servers to be utilized in this request - - - `String name` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `Optional authorizationToken` - - - `Optional toolConfiguration` - - - `Optional> allowedTools` - - - `Optional enabled` - - - `Optional metadata` - - An object describing metadata about the request. - - - `Optional outputConfig` - - Configuration options for the model's output, such as the output format. - - - `Optional outputFormat` - - Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - - A schema to specify Claude's output format in responses. This parameter will be removed in a future release. - - - `Optional serviceTier` - - Determines whether to use priority capacity (if available) or standard capacity for this request. - - Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. - - - `AUTO("auto")` - - - `STANDARD_ONLY("standard_only")` - - - `Optional speed` - - The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. - - - `STANDARD("standard")` - - - `FAST("fast")` - - - `Optional> stopSequences` - - Custom text sequences that will cause the model to stop generating. - - Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. - - If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. - - - `Optional system` - - System prompt. - - A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). - - - `String` - - - `List` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `Optional temperature` - - Amount of randomness injected into the response. - - Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. - - Note that even with `temperature` of `0.0`, the results will not be fully deterministic. - - - `Optional thinking` - - Configuration for enabling Claude's extended thinking. - - When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `Optional toolChoice` - - How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. - - - `Optional> tools` - - Definitions of tools that the model may use. - - If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. - - There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). - - Each tool definition includes: - - * `name`: Name of the tool. - * `description`: Optional, but strongly-recommended description of the tool. - * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. - - For example, if you defined `tools` as: - - ```json - [ - { - "name": "get_stock_price", - "description": "Get the current stock price for a given ticker symbol.", - "input_schema": { - "type": "object", - "properties": { - "ticker": { - "type": "string", - "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." - } - }, - "required": ["ticker"] - } - } - ] - ``` - - And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: - - ```json - [ - { - "type": "tool_use", - "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "name": "get_stock_price", - "input": { "ticker": "^GSPC" } - } - ] - ``` - - You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: - - ```json - [ - { - "type": "tool_result", - "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "content": "259.75 USD" - } - ] - ``` - - Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. - - See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. - - - `class BetaTool:` - - - `InputSchema inputSchema` - - [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. - - This defines the shape of the `input` that your tool accepts and that the model will produce. - - - `JsonValue; type "object"constant` - - - `OBJECT("object")` - - - `Optional properties` - - - `Optional> required` - - - `String name` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional description` - - Description of what this tool does. - - Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - - - `Optional eagerInputStreaming` - - Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional type` - - - `CUSTOM("custom")` - - - `class BetaToolBash20241022:` - - - `JsonValue; name "bash"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `BASH("bash")` - - - `JsonValue; type "bash_20241022"constant` - - - `BASH_20241022("bash_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolBash20250124:` - - - `JsonValue; name "bash"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `BASH("bash")` - - - `JsonValue; type "bash_20250124"constant` - - - `BASH_20250124("bash_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaCodeExecutionTool20250522:` - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20250522"constant` - - - `CODE_EXECUTION_20250522("code_execution_20250522")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaCodeExecutionTool20250825:` - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaCodeExecutionTool20260120:` - - Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolComputerUse20241022:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20241022"constant` - - - `COMPUTER_20241022("computer_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaMemoryTool20250818:` - - - `JsonValue; name "memory"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `MEMORY("memory")` - - - `JsonValue; type "memory_20250818"constant` - - - `MEMORY_20250818("memory_20250818")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolComputerUse20250124:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20250124"constant` - - - `COMPUTER_20250124("computer_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20241022:` - - - `JsonValue; name "str_replace_editor"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_EDITOR("str_replace_editor")` - - - `JsonValue; type "text_editor_20241022"constant` - - - `TEXT_EDITOR_20241022("text_editor_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolComputerUse20251124:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20251124"constant` - - - `COMPUTER_20251124("computer_20251124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional enableZoom` - - Whether to enable an action to take a zoomed-in screenshot of the screen. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20250124:` - - - `JsonValue; name "str_replace_editor"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_EDITOR("str_replace_editor")` - - - `JsonValue; type "text_editor_20250124"constant` - - - `TEXT_EDITOR_20250124("text_editor_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20250429:` - - - `JsonValue; name "str_replace_based_edit_tool"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")` - - - `JsonValue; type "text_editor_20250429"constant` - - - `TEXT_EDITOR_20250429("text_editor_20250429")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20250728:` - - - `JsonValue; name "str_replace_based_edit_tool"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")` - - - `JsonValue; type "text_editor_20250728"constant` - - - `TEXT_EDITOR_20250728("text_editor_20250728")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional maxCharacters` - - Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaWebSearchTool20250305:` - - - `JsonValue; name "web_search"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_SEARCH("web_search")` - - - `JsonValue; type "web_search_20250305"constant` - - - `WEB_SEARCH_20250305("web_search_20250305")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `Optional> blockedDomains` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional userLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `JsonValue; type "approximate"constant` - - - `APPROXIMATE("approximate")` - - - `Optional city` - - The city of the user. - - - `Optional country` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `Optional region` - - The region of the user. - - - `Optional timezone` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `class BetaWebFetchTool20250910:` - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20250910"constant` - - - `WEB_FETCH_20250910("web_fetch_20250910")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaWebSearchTool20260209:` - - - `JsonValue; name "web_search"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_SEARCH("web_search")` - - - `JsonValue; type "web_search_20260209"constant` - - - `WEB_SEARCH_20260209("web_search_20260209")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `Optional> blockedDomains` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional userLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `JsonValue; type "approximate"constant` - - - `APPROXIMATE("approximate")` - - - `Optional city` - - The city of the user. - - - `Optional country` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `Optional region` - - The region of the user. - - - `Optional timezone` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `class BetaWebFetchTool20260209:` - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20260209"constant` - - - `WEB_FETCH_20260209("web_fetch_20260209")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaWebFetchTool20260309:` - - Web fetch tool with use_cache parameter for bypassing cached content. - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20260309"constant` - - - `WEB_FETCH_20260309("web_fetch_20260309")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional useCache` - - Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - - - `class BetaToolSearchToolBm25_20251119:` - - - `JsonValue; name "tool_search_tool_bm25"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `Type type` - - - `TOOL_SEARCH_TOOL_BM25_20251119("tool_search_tool_bm25_20251119")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolSearchToolRegex20251119:` - - - `JsonValue; name "tool_search_tool_regex"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `Type type` - - - `TOOL_SEARCH_TOOL_REGEX_20251119("tool_search_tool_regex_20251119")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaMcpToolset:` - - Configuration for a group of tools from an MCP server. - - Allows configuring enabled status and defer_loading for all tools - from an MCP server, with optional per-tool overrides. - - - `String mcpServerName` - - Name of the MCP server to configure tools for - - - `JsonValue; type "mcp_toolset"constant` - - - `MCP_TOOLSET("mcp_toolset")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional configs` - - Configuration overrides for specific tools, keyed by tool name - - - `Optional deferLoading` - - - `Optional enabled` - - - `Optional defaultConfig` - - Default configuration applied to all tools from this server - - - `Optional deferLoading` - - - `Optional enabled` - - - `Optional topK` - - Only sample from the top K options for each subsequent token. - - Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). - - Recommended for advanced use cases only. You usually only need to use `temperature`. - - - `Optional topP` - - Use nucleus sampling. - - In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. - - Recommended for advanced use cases only. You usually only need to use `temperature`. - - - `Optional userProfileId` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - -### Returns - -- `class BetaMessage:` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional container` - - Information about the container used in the request (for the code execution tool) - - - `String id` - - Identifier for the container used in this request - - - `LocalDateTime expiresAt` - - The time at which the container will expire. - - - `Optional> skills` - - Skills loaded in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `String version` - - Skill version or 'latest' for most recent version - - - `List content` - - Content generated by the model. - - This is an array of content blocks, each of which has a `type` that determines its shape. - - Example: - - ```json - [{"type": "text", "text": "Hi, I'm Claude."}] - ``` - - If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. - - For example, if the input `messages` were: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("} - ] - ``` - - Then the response `content` might be: - - ```json - [{"type": "text", "text": "B)"}] - ``` - - - `class BetaTextBlock:` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaThinkingBlock:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlock:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaServerToolUseBlock:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlock:` - - - `BetaWebSearchToolResultBlockContent content` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlock:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlock:` - - - `BetaCodeExecutionToolResultBlockContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `class BetaBashCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `class BetaTextEditorCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `class BetaToolSearchToolResultBlock:` - - - `Content content` - - - `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `class BetaMcpToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - The name of the MCP tool - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `class BetaMcpToolResultBlock:` - - - `Content content` - - - `String` - - - `List` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `boolean isError` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `class BetaContainerUploadBlock:` - - Response model for a file uploaded to the container. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `class BetaCompactionBlock:` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `Optional content` - - Summary of compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional contextManagement` - - Context management response. - - Information about context management strategies applied during the request. - - - `List appliedEdits` - - List of context management edits that were applied. - - - `class BetaClearToolUses20250919EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedToolUses` - - Number of tool uses that were cleared. - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - The type of context management edit applied. - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `class BetaClearThinking20251015EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedThinkingTurns` - - Number of thinking turns that were cleared. - - - `JsonValue; type "clear_thinking_20251015"constant` - - The type of context management edit applied. - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Model model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - - Most intelligent model for building agents and coding - - - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` - - Best combination of speed and intelligence - - - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_OPUS_4_5("claude-opus-4-5")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` - - High-performance model for agents and coding - - - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` - - High-performance model for agents and coding - - - `CLAUDE_OPUS_4_1("claude-opus-4-1")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_0("claude-opus-4-0")` - - Powerful model for complex tasks - - - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")` - - Powerful model for complex tasks - - - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")` - - High-performance model with extended thinking - - - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")` - - High-performance model with extended thinking - - - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")` - - Fast and cost-effective model - - - `JsonValue; role "assistant"constant` - - Conversational role of the generated message. - - This will always be `"assistant"`. - - - `ASSISTANT("assistant")` - - - `Optional stopDetails` - - Structured information about a refusal. - - - `Optional category` - - The policy category that triggered the refusal. - - `null` when the refusal doesn't map to a named category. - - - `CYBER("cyber")` - - - `BIO("bio")` - - - `Optional explanation` - - Human-readable explanation of the refusal. - - This text is not guaranteed to be stable. `null` when no explanation is available for the category. - - - `JsonValue; type "refusal"constant` - - - `REFUSAL("refusal")` - - - `Optional stopReason` - - The reason that we stopped. - - This may be one the following values: - - * `"end_turn"`: the model reached a natural stopping point - * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - * `"tool_use"`: the model invoked one or more tools - * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - * `"refusal"`: when streaming classifiers intervene to handle potential policy violations - - In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - - - `END_TURN("end_turn")` - - - `MAX_TOKENS("max_tokens")` - - - `STOP_SEQUENCE("stop_sequence")` - - - `TOOL_USE("tool_use")` - - - `PAUSE_TURN("pause_turn")` - - - `COMPACTION("compaction")` - - - `REFUSAL("refusal")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")` - - - `Optional stopSequence` - - Which custom stop sequence was generated, if any. - - This value will be a non-null string if one of your custom stop sequences was generated. - - - `JsonValue; type "message"constant` - - Object type. - - For Messages, this is always `"message"`. - - - `MESSAGE("message")` - - - `BetaUsage usage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `Optional cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `Optional cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `Optional inferenceGeo` - - The geographic region where inference was performed for this request. - - - `long inputTokens` - - The number of input tokens which were used. - - - `Optional> iterations` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - - - `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - - - `long outputTokens` - - The number of output tokens which were used. - - - `Optional serverToolUse` - - The number of server tool requests. - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - - - `Optional serviceTier` - - If the request used the priority, standard, or batch tier. - - - `STANDARD("standard")` - - - `PRIORITY("priority")` - - - `BATCH("batch")` - - - `Optional speed` - - The inference speed mode used for this request. - - - `STANDARD("standard")` - - - `FAST("fast")` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.messages.BetaMessage; -import com.anthropic.models.beta.messages.MessageCreateParams; -import com.anthropic.models.messages.Model; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - MessageCreateParams params = MessageCreateParams.builder() - .maxTokens(1024L) - .addUserMessage("Hello, world") - .model(Model.CLAUDE_OPUS_4_6) - .build(); - BetaMessage betaMessage = client.beta().messages().create(params); - } -} -``` - -## Count Tokens - -`BetaMessageTokensCount beta().messages().countTokens(MessageCountTokensParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - -**post** `/v1/messages/count_tokens` - -Count the number of tokens in a Message. - -The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it. - -Learn more about token counting in our [user guide](https://docs.claude.com/en/docs/build-with-claude/token-counting) - -### Parameters - -- `MessageCountTokensParams params` - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - - `List messages` - - Input messages. - - Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. - - Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. - - If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. - - Example with a single `user` message: - - ```json - [{"role": "user", "content": "Hello, Claude"}] - ``` - - Example with multiple conversational turns: - - ```json - [ - {"role": "user", "content": "Hello there."}, - {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, - {"role": "user", "content": "Can you explain LLMs in plain English?"}, - ] - ``` - - Example with a partially-filled response from Claude: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("}, - ] - ``` - - Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: - - ```json - {"role": "user", "content": "Hello, Claude"} - ``` - - ```json - {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} - ``` - - See [input examples](https://docs.claude.com/en/api/messages-examples). - - Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. - - There is a limit of 100,000 messages in a single request. - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaRequestDocumentBlock:` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `class BetaSearchResultBlockParam:` - - - `List content` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String source` - - - `String title` - - - `JsonValue; type "search_result"constant` - - - `SEARCH_RESULT("search_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `class BetaThinkingBlockParam:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlockParam:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaToolResultBlockParam:` - - - `String toolUseId` - - - `JsonValue; type "tool_result"constant` - - - `TOOL_RESULT("tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaSearchResultBlockParam:` - - - `List content` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String source` - - - `String title` - - - `JsonValue; type "search_result"constant` - - - `SEARCH_RESULT("search_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `class BetaRequestDocumentBlock:` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `class BetaToolReferenceBlockParam:` - - Tool reference block that can be included in tool_result content. - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional isError` - - - `class BetaServerToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlockParam:` - - - `BetaWebSearchToolResultBlockParamContent content` - - - `List` - - - `String encryptedContent` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `Optional pageAge` - - - `class BetaWebSearchToolRequestError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlockParam:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlockParam:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlockParam:` - - - `BetaRequestDocumentBlock content` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlockParam:` - - - `BetaCodeExecutionToolResultBlockParamContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultErrorParam:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlockParam:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaBashCodeExecutionToolResultBlockParam:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaTextEditorCodeExecutionToolResultBlockParam:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `Optional errorMessage` - - - `class BetaTextEditorCodeExecutionViewResultBlockParam:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `class BetaTextEditorCodeExecutionCreateResultBlockParam:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaToolSearchToolResultBlockParam:` - - - `Content content` - - - `class BetaToolSearchToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlockParam:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaMcpToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `String name` - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaRequestMcpToolResultBlockParam:` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional content` - - - `String` - - - `List` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `Optional isError` - - - `class BetaContainerUploadBlockParam:` - - A content block that represents a file to be uploaded to the container - Files uploaded via this block will be available in the container's input directory. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaCompactionBlockParam:` - - A compaction block containing summary of previous context. - - Users should round-trip these blocks from responses to subsequent requests - to maintain context across compaction boundaries. - - When content is None, the block represents a failed compaction. The server - treats these as no-ops. Empty string content is not allowed. - - - `Optional content` - - Summary of previously compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Role role` - - - `USER("user")` - - - `ASSISTANT("assistant")` - - - `Model model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `Optional cacheControl` - - Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - - - `Optional contextManagement` - - Context management configuration. - - This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. - - - `Optional> mcpServers` - - MCP servers to be utilized in this request - - - `String name` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `Optional authorizationToken` - - - `Optional toolConfiguration` - - - `Optional> allowedTools` - - - `Optional enabled` - - - `Optional outputConfig` - - Configuration options for the model's output, such as the output format. - - - `Optional outputFormat` - - Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - - A schema to specify Claude's output format in responses. This parameter will be removed in a future release. - - - `Optional speed` - - The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. - - - `STANDARD("standard")` - - - `FAST("fast")` - - - `Optional system` - - System prompt. - - A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). - - - `String` - - - `List` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `Optional thinking` - - Configuration for enabling Claude's extended thinking. - - When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `Optional toolChoice` - - How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. - - - `Optional> tools` - - Definitions of tools that the model may use. - - If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. - - There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). - - Each tool definition includes: - - * `name`: Name of the tool. - * `description`: Optional, but strongly-recommended description of the tool. - * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. - - For example, if you defined `tools` as: - - ```json - [ - { - "name": "get_stock_price", - "description": "Get the current stock price for a given ticker symbol.", - "input_schema": { - "type": "object", - "properties": { - "ticker": { - "type": "string", - "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." - } - }, - "required": ["ticker"] - } - } - ] - ``` - - And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: - - ```json - [ - { - "type": "tool_use", - "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "name": "get_stock_price", - "input": { "ticker": "^GSPC" } - } - ] - ``` - - You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: - - ```json - [ - { - "type": "tool_result", - "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "content": "259.75 USD" - } - ] - ``` - - Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. - - See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. - - - `class BetaTool:` - - - `InputSchema inputSchema` - - [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. - - This defines the shape of the `input` that your tool accepts and that the model will produce. - - - `JsonValue; type "object"constant` - - - `OBJECT("object")` - - - `Optional properties` - - - `Optional> required` - - - `String name` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional description` - - Description of what this tool does. - - Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - - - `Optional eagerInputStreaming` - - Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional type` - - - `CUSTOM("custom")` - - - `class BetaToolBash20241022:` - - - `JsonValue; name "bash"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `BASH("bash")` - - - `JsonValue; type "bash_20241022"constant` - - - `BASH_20241022("bash_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolBash20250124:` - - - `JsonValue; name "bash"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `BASH("bash")` - - - `JsonValue; type "bash_20250124"constant` - - - `BASH_20250124("bash_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaCodeExecutionTool20250522:` - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20250522"constant` - - - `CODE_EXECUTION_20250522("code_execution_20250522")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaCodeExecutionTool20250825:` - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaCodeExecutionTool20260120:` - - Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolComputerUse20241022:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20241022"constant` - - - `COMPUTER_20241022("computer_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaMemoryTool20250818:` - - - `JsonValue; name "memory"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `MEMORY("memory")` - - - `JsonValue; type "memory_20250818"constant` - - - `MEMORY_20250818("memory_20250818")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolComputerUse20250124:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20250124"constant` - - - `COMPUTER_20250124("computer_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20241022:` - - - `JsonValue; name "str_replace_editor"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_EDITOR("str_replace_editor")` - - - `JsonValue; type "text_editor_20241022"constant` - - - `TEXT_EDITOR_20241022("text_editor_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolComputerUse20251124:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20251124"constant` - - - `COMPUTER_20251124("computer_20251124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional enableZoom` - - Whether to enable an action to take a zoomed-in screenshot of the screen. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20250124:` - - - `JsonValue; name "str_replace_editor"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_EDITOR("str_replace_editor")` - - - `JsonValue; type "text_editor_20250124"constant` - - - `TEXT_EDITOR_20250124("text_editor_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20250429:` - - - `JsonValue; name "str_replace_based_edit_tool"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")` - - - `JsonValue; type "text_editor_20250429"constant` - - - `TEXT_EDITOR_20250429("text_editor_20250429")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20250728:` - - - `JsonValue; name "str_replace_based_edit_tool"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")` - - - `JsonValue; type "text_editor_20250728"constant` - - - `TEXT_EDITOR_20250728("text_editor_20250728")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional maxCharacters` - - Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaWebSearchTool20250305:` - - - `JsonValue; name "web_search"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_SEARCH("web_search")` - - - `JsonValue; type "web_search_20250305"constant` - - - `WEB_SEARCH_20250305("web_search_20250305")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `Optional> blockedDomains` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional userLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `JsonValue; type "approximate"constant` - - - `APPROXIMATE("approximate")` - - - `Optional city` - - The city of the user. - - - `Optional country` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `Optional region` - - The region of the user. - - - `Optional timezone` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `class BetaWebFetchTool20250910:` - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20250910"constant` - - - `WEB_FETCH_20250910("web_fetch_20250910")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaWebSearchTool20260209:` - - - `JsonValue; name "web_search"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_SEARCH("web_search")` - - - `JsonValue; type "web_search_20260209"constant` - - - `WEB_SEARCH_20260209("web_search_20260209")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `Optional> blockedDomains` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional userLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `JsonValue; type "approximate"constant` - - - `APPROXIMATE("approximate")` - - - `Optional city` - - The city of the user. - - - `Optional country` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `Optional region` - - The region of the user. - - - `Optional timezone` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `class BetaWebFetchTool20260209:` - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20260209"constant` - - - `WEB_FETCH_20260209("web_fetch_20260209")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaWebFetchTool20260309:` - - Web fetch tool with use_cache parameter for bypassing cached content. - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20260309"constant` - - - `WEB_FETCH_20260309("web_fetch_20260309")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional useCache` - - Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - - - `class BetaToolSearchToolBm25_20251119:` - - - `JsonValue; name "tool_search_tool_bm25"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `Type type` - - - `TOOL_SEARCH_TOOL_BM25_20251119("tool_search_tool_bm25_20251119")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolSearchToolRegex20251119:` - - - `JsonValue; name "tool_search_tool_regex"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `Type type` - - - `TOOL_SEARCH_TOOL_REGEX_20251119("tool_search_tool_regex_20251119")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaMcpToolset:` - - Configuration for a group of tools from an MCP server. - - Allows configuring enabled status and defer_loading for all tools - from an MCP server, with optional per-tool overrides. - - - `String mcpServerName` - - Name of the MCP server to configure tools for - - - `JsonValue; type "mcp_toolset"constant` - - - `MCP_TOOLSET("mcp_toolset")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional configs` - - Configuration overrides for specific tools, keyed by tool name - - - `Optional deferLoading` - - - `Optional enabled` - - - `Optional defaultConfig` - - Default configuration applied to all tools from this server - - - `Optional deferLoading` - - - `Optional enabled` - -### Returns - -- `class BetaMessageTokensCount:` - - - `Optional contextManagement` - - Information about context management applied to the message. - - - `long originalInputTokens` - - The original token count before context management was applied - - - `long inputTokens` - - The total number of tokens across the provided list of messages, system prompt, and tools. - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.messages.BetaMessageTokensCount; -import com.anthropic.models.beta.messages.MessageCountTokensParams; -import com.anthropic.models.messages.Model; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - MessageCountTokensParams params = MessageCountTokensParams.builder() - .addUserMessage("Hello, world") - .model(Model.CLAUDE_OPUS_4_6) - .build(); - BetaMessageTokensCount betaMessageTokensCount = client.beta().messages().countTokens(params); - } -} -``` - -## Domain Types - -### Beta All Thinking Turns - -- `class BetaAllThinkingTurns:` - - - `JsonValue; type "all"constant` - - - `ALL("all")` - -### Beta Base64 Image Source - -- `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - -### Beta Base64 PDF Source - -- `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - -### Beta Bash Code Execution Output Block - -- `class BetaBashCodeExecutionOutputBlock:` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - -### Beta Bash Code Execution Output Block Param - -- `class BetaBashCodeExecutionOutputBlockParam:` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - -### Beta Bash Code Execution Result Block - -- `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - -### Beta Bash Code Execution Result Block Param - -- `class BetaBashCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - -### Beta Bash Code Execution Tool Result Block - -- `class BetaBashCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - -### Beta Bash Code Execution Tool Result Block Param - -- `class BetaBashCodeExecutionToolResultBlockParam:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - -### Beta Bash Code Execution Tool Result Error - -- `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - -### Beta Bash Code Execution Tool Result Error Param - -- `class BetaBashCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - -### Beta Cache Control Ephemeral - -- `class BetaCacheControlEphemeral:` - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - -### Beta Cache Creation - -- `class BetaCacheCreation:` - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - -### Beta Citation Char Location - -- `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - -### Beta Citation Char Location Param - -- `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - -### Beta Citation Config - -- `class BetaCitationConfig:` - - - `boolean enabled` - -### Beta Citation Content Block Location - -- `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - -### Beta Citation Content Block Location Param - -- `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - -### Beta Citation Page Location - -- `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - -### Beta Citation Page Location Param - -- `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - -### Beta Citation Search Result Location - -- `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - -### Beta Citation Search Result Location Param - -- `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - -### Beta Citation Web Search Result Location Param - -- `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - -### Beta Citations Config Param - -- `class BetaCitationsConfigParam:` - - - `Optional enabled` - -### Beta Citations Delta - -- `class BetaCitationsDelta:` - - - `Citation citation` - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `JsonValue; type "citations_delta"constant` - - - `CITATIONS_DELTA("citations_delta")` - -### Beta Citations Web Search Result Location - -- `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - -### Beta Clear Thinking 20251015 Edit - -- `class BetaClearThinking20251015Edit:` - - - `JsonValue; type "clear_thinking_20251015"constant` - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Optional keep` - - Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. - - - `class BetaThinkingTurns:` - - - `JsonValue; type "thinking_turns"constant` - - - `THINKING_TURNS("thinking_turns")` - - - `long value` - - - `class BetaAllThinkingTurns:` - - - `JsonValue; type "all"constant` - - - `ALL("all")` - - - `JsonValue;` - - - `ALL("all")` - -### Beta Clear Thinking 20251015 Edit Response - -- `class BetaClearThinking20251015EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedThinkingTurns` - - Number of thinking turns that were cleared. - - - `JsonValue; type "clear_thinking_20251015"constant` - - The type of context management edit applied. - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - -### Beta Clear Tool Uses 20250919 Edit - -- `class BetaClearToolUses20250919Edit:` - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `Optional clearAtLeast` - - Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed. - - - `JsonValue; type "input_tokens"constant` - - - `INPUT_TOKENS("input_tokens")` - - - `long value` - - - `Optional clearToolInputs` - - Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) - - - `boolean` - - - `List` - - - `Optional> excludeTools` - - Tool names whose uses are preserved from clearing - - - `Optional keep` - - Number of tool uses to retain in the conversation - - - `JsonValue; type "tool_uses"constant` - - - `TOOL_USES("tool_uses")` - - - `long value` - - - `Optional trigger` - - Condition that triggers the context management strategy - - - `class BetaInputTokensTrigger:` - - - `JsonValue; type "input_tokens"constant` - - - `INPUT_TOKENS("input_tokens")` - - - `long value` - - - `class BetaToolUsesTrigger:` - - - `JsonValue; type "tool_uses"constant` - - - `TOOL_USES("tool_uses")` - - - `long value` - -### Beta Clear Tool Uses 20250919 Edit Response - -- `class BetaClearToolUses20250919EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedToolUses` - - Number of tool uses that were cleared. - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - The type of context management edit applied. - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - -### Beta Code Execution Output Block - -- `class BetaCodeExecutionOutputBlock:` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - -### Beta Code Execution Output Block Param - -- `class BetaCodeExecutionOutputBlockParam:` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - -### Beta Code Execution Result Block - -- `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - -### Beta Code Execution Result Block Param - -- `class BetaCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - -### Beta Code Execution Tool 20250522 - -- `class BetaCodeExecutionTool20250522:` - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20250522"constant` - - - `CODE_EXECUTION_20250522("code_execution_20250522")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Code Execution Tool 20250825 - -- `class BetaCodeExecutionTool20250825:` - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Code Execution Tool 20260120 - -- `class BetaCodeExecutionTool20260120:` - - Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Code Execution Tool Result Block - -- `class BetaCodeExecutionToolResultBlock:` - - - `BetaCodeExecutionToolResultBlockContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - -### Beta Code Execution Tool Result Block Content - -- `class BetaCodeExecutionToolResultBlockContent: A class that can be one of several variants.union` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - -### Beta Code Execution Tool Result Block Param - -- `class BetaCodeExecutionToolResultBlockParam:` - - - `BetaCodeExecutionToolResultBlockParamContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultErrorParam:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlockParam:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - -### Beta Code Execution Tool Result Block Param Content - -- `class BetaCodeExecutionToolResultBlockParamContent: A class that can be one of several variants.union` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultErrorParam:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlockParam:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - -### Beta Code Execution Tool Result Error - -- `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - -### Beta Code Execution Tool Result Error Code - -- `enum BetaCodeExecutionToolResultErrorCode:` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - -### Beta Code Execution Tool Result Error Param - -- `class BetaCodeExecutionToolResultErrorParam:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - -### Beta Compact 20260112 Edit - -- `class BetaCompact20260112Edit:` - - Automatically compact older context when reaching the configured trigger threshold. - - - `JsonValue; type "compact_20260112"constant` - - - `COMPACT_20260112("compact_20260112")` - - - `Optional instructions` - - Additional instructions for summarization. - - - `Optional pauseAfterCompaction` - - Whether to pause after compaction and return the compaction block to the user. - - - `Optional trigger` - - When to trigger compaction. Defaults to 150000 input tokens. - - - `JsonValue; type "input_tokens"constant` - - - `INPUT_TOKENS("input_tokens")` - - - `long value` - -### Beta Compaction Block - -- `class BetaCompactionBlock:` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `Optional content` - - Summary of compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - -### Beta Compaction Block Param - -- `class BetaCompactionBlockParam:` - - A compaction block containing summary of previous context. - - Users should round-trip these blocks from responses to subsequent requests - to maintain context across compaction boundaries. - - When content is None, the block represents a failed compaction. The server - treats these as no-ops. Empty string content is not allowed. - - - `Optional content` - - Summary of previously compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - -### Beta Compaction Content Block Delta - -- `class BetaCompactionContentBlockDelta:` - - - `Optional content` - - - `JsonValue; type "compaction_delta"constant` - - - `COMPACTION_DELTA("compaction_delta")` - -### Beta Compaction Iteration Usage - -- `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - -### Beta Container - -- `class BetaContainer:` - - Information about the container used in the request (for the code execution tool) - - - `String id` - - Identifier for the container used in this request - - - `LocalDateTime expiresAt` - - The time at which the container will expire. - - - `Optional> skills` - - Skills loaded in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `String version` - - Skill version or 'latest' for most recent version - -### Beta Container Params - -- `class BetaContainerParams:` - - Container parameters with skills to be loaded. - - - `Optional id` - - Container id - - - `Optional> skills` - - List of skills to load in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `Optional version` - - Skill version or 'latest' for most recent version - -### Beta Container Upload Block - -- `class BetaContainerUploadBlock:` - - Response model for a file uploaded to the container. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - -### Beta Container Upload Block Param - -- `class BetaContainerUploadBlockParam:` - - A content block that represents a file to be uploaded to the container - Files uploaded via this block will be available in the container's input directory. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - -### Beta Content Block - -- `class BetaContentBlock: A class that can be one of several variants.union` - - Response model for a file uploaded to the container. - - - `class BetaTextBlock:` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaThinkingBlock:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlock:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaServerToolUseBlock:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlock:` - - - `BetaWebSearchToolResultBlockContent content` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlock:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlock:` - - - `BetaCodeExecutionToolResultBlockContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `class BetaBashCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `class BetaTextEditorCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `class BetaToolSearchToolResultBlock:` - - - `Content content` - - - `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `class BetaMcpToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - The name of the MCP tool - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `class BetaMcpToolResultBlock:` - - - `Content content` - - - `String` - - - `List` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `boolean isError` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `class BetaContainerUploadBlock:` - - Response model for a file uploaded to the container. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `class BetaCompactionBlock:` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `Optional content` - - Summary of compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - -### Beta Content Block Param - -- `class BetaContentBlockParam: A class that can be one of several variants.union` - - Regular text content. - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaRequestDocumentBlock:` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `class BetaSearchResultBlockParam:` - - - `List content` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String source` - - - `String title` - - - `JsonValue; type "search_result"constant` - - - `SEARCH_RESULT("search_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `class BetaThinkingBlockParam:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlockParam:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaToolResultBlockParam:` - - - `String toolUseId` - - - `JsonValue; type "tool_result"constant` - - - `TOOL_RESULT("tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaSearchResultBlockParam:` - - - `List content` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String source` - - - `String title` - - - `JsonValue; type "search_result"constant` - - - `SEARCH_RESULT("search_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `class BetaRequestDocumentBlock:` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `class BetaToolReferenceBlockParam:` - - Tool reference block that can be included in tool_result content. - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional isError` - - - `class BetaServerToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlockParam:` - - - `BetaWebSearchToolResultBlockParamContent content` - - - `List` - - - `String encryptedContent` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `Optional pageAge` - - - `class BetaWebSearchToolRequestError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlockParam:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlockParam:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlockParam:` - - - `BetaRequestDocumentBlock content` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlockParam:` - - - `BetaCodeExecutionToolResultBlockParamContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultErrorParam:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlockParam:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaBashCodeExecutionToolResultBlockParam:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaTextEditorCodeExecutionToolResultBlockParam:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `Optional errorMessage` - - - `class BetaTextEditorCodeExecutionViewResultBlockParam:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `class BetaTextEditorCodeExecutionCreateResultBlockParam:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaToolSearchToolResultBlockParam:` - - - `Content content` - - - `class BetaToolSearchToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlockParam:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaMcpToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `String name` - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaRequestMcpToolResultBlockParam:` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional content` - - - `String` - - - `List` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `Optional isError` - - - `class BetaContainerUploadBlockParam:` - - A content block that represents a file to be uploaded to the container - Files uploaded via this block will be available in the container's input directory. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaCompactionBlockParam:` - - A compaction block containing summary of previous context. - - Users should round-trip these blocks from responses to subsequent requests - to maintain context across compaction boundaries. - - When content is None, the block represents a failed compaction. The server - treats these as no-ops. Empty string content is not allowed. - - - `Optional content` - - Summary of previously compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - -### Beta Content Block Source - -- `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - -### Beta Content Block Source Content - -- `class BetaContentBlockSourceContent: A class that can be one of several variants.union` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - -### Beta Context Management Config - -- `class BetaContextManagementConfig:` - - - `Optional> edits` - - List of context management edits to apply - - - `class BetaClearToolUses20250919Edit:` - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `Optional clearAtLeast` - - Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed. - - - `JsonValue; type "input_tokens"constant` - - - `INPUT_TOKENS("input_tokens")` - - - `long value` - - - `Optional clearToolInputs` - - Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) - - - `boolean` - - - `List` - - - `Optional> excludeTools` - - Tool names whose uses are preserved from clearing - - - `Optional keep` - - Number of tool uses to retain in the conversation - - - `JsonValue; type "tool_uses"constant` - - - `TOOL_USES("tool_uses")` - - - `long value` - - - `Optional trigger` - - Condition that triggers the context management strategy - - - `class BetaInputTokensTrigger:` - - - `JsonValue; type "input_tokens"constant` - - - `INPUT_TOKENS("input_tokens")` - - - `long value` - - - `class BetaToolUsesTrigger:` - - - `JsonValue; type "tool_uses"constant` - - - `TOOL_USES("tool_uses")` - - - `long value` - - - `class BetaClearThinking20251015Edit:` - - - `JsonValue; type "clear_thinking_20251015"constant` - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Optional keep` - - Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. - - - `class BetaThinkingTurns:` - - - `JsonValue; type "thinking_turns"constant` - - - `THINKING_TURNS("thinking_turns")` - - - `long value` - - - `class BetaAllThinkingTurns:` - - - `JsonValue; type "all"constant` - - - `ALL("all")` - - - `JsonValue;` - - - `ALL("all")` - - - `class BetaCompact20260112Edit:` - - Automatically compact older context when reaching the configured trigger threshold. - - - `JsonValue; type "compact_20260112"constant` - - - `COMPACT_20260112("compact_20260112")` - - - `Optional instructions` - - Additional instructions for summarization. - - - `Optional pauseAfterCompaction` - - Whether to pause after compaction and return the compaction block to the user. - - - `Optional trigger` - - When to trigger compaction. Defaults to 150000 input tokens. - - - `JsonValue; type "input_tokens"constant` - - - `INPUT_TOKENS("input_tokens")` - - - `long value` - -### Beta Context Management Response - -- `class BetaContextManagementResponse:` - - - `List appliedEdits` - - List of context management edits that were applied. - - - `class BetaClearToolUses20250919EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedToolUses` - - Number of tool uses that were cleared. - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - The type of context management edit applied. - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `class BetaClearThinking20251015EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedThinkingTurns` - - Number of thinking turns that were cleared. - - - `JsonValue; type "clear_thinking_20251015"constant` - - The type of context management edit applied. - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - -### Beta Count Tokens Context Management Response - -- `class BetaCountTokensContextManagementResponse:` - - - `long originalInputTokens` - - The original token count before context management was applied - -### Beta Direct Caller - -- `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - -### Beta Document Block - -- `class BetaDocumentBlock:` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - -### Beta Encrypted Code Execution Result Block - -- `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - -### Beta Encrypted Code Execution Result Block Param - -- `class BetaEncryptedCodeExecutionResultBlockParam:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - -### Beta File Document Source - -- `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - -### Beta File Image Source - -- `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - -### Beta Image Block Param - -- `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - -### Beta Input JSON Delta - -- `class BetaInputJsonDelta:` - - - `String partialJson` - - - `JsonValue; type "input_json_delta"constant` - - - `INPUT_JSON_DELTA("input_json_delta")` - -### Beta Input Tokens Clear At Least - -- `class BetaInputTokensClearAtLeast:` - - - `JsonValue; type "input_tokens"constant` - - - `INPUT_TOKENS("input_tokens")` - - - `long value` - -### Beta Input Tokens Trigger - -- `class BetaInputTokensTrigger:` - - - `JsonValue; type "input_tokens"constant` - - - `INPUT_TOKENS("input_tokens")` - - - `long value` - -### Beta JSON Output Format - -- `class BetaJsonOutputFormat:` - - - `Schema schema` - - The JSON schema of the format - - - `JsonValue; type "json_schema"constant` - - - `JSON_SCHEMA("json_schema")` - -### Beta MCP Tool Config - -- `class BetaMcpToolConfig:` - - Configuration for a specific tool in an MCP toolset. - - - `Optional deferLoading` - - - `Optional enabled` - -### Beta MCP Tool Default Config - -- `class BetaMcpToolDefaultConfig:` - - Default configuration for tools in an MCP toolset. - - - `Optional deferLoading` - - - `Optional enabled` - -### Beta MCP Tool Result Block - -- `class BetaMcpToolResultBlock:` - - - `Content content` - - - `String` - - - `List` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `boolean isError` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - -### Beta MCP Tool Use Block - -- `class BetaMcpToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - The name of the MCP tool - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - -### Beta MCP Tool Use Block Param - -- `class BetaMcpToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `String name` - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - -### Beta MCP Toolset - -- `class BetaMcpToolset:` - - Configuration for a group of tools from an MCP server. - - Allows configuring enabled status and defer_loading for all tools - from an MCP server, with optional per-tool overrides. - - - `String mcpServerName` - - Name of the MCP server to configure tools for - - - `JsonValue; type "mcp_toolset"constant` - - - `MCP_TOOLSET("mcp_toolset")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional configs` - - Configuration overrides for specific tools, keyed by tool name - - - `Optional deferLoading` - - - `Optional enabled` - - - `Optional defaultConfig` - - Default configuration applied to all tools from this server - - - `Optional deferLoading` - - - `Optional enabled` - -### Beta Memory Tool 20250818 - -- `class BetaMemoryTool20250818:` - - - `JsonValue; name "memory"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `MEMORY("memory")` - - - `JsonValue; type "memory_20250818"constant` - - - `MEMORY_20250818("memory_20250818")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Memory Tool 20250818 Command - -- `class BetaMemoryTool20250818Command: A class that can be one of several variants.union` - - - `class BetaMemoryTool20250818ViewCommand:` - - - `JsonValue; command "view"constant` - - Command type identifier - - - `VIEW("view")` - - - `String path` - - Path to directory or file to view - - - `Optional> viewRange` - - Optional line range for viewing specific lines - - - `class BetaMemoryTool20250818CreateCommand:` - - - `JsonValue; command "create"constant` - - Command type identifier - - - `CREATE("create")` - - - `String fileText` - - Content to write to the file - - - `String path` - - Path where the file should be created - - - `class BetaMemoryTool20250818StrReplaceCommand:` - - - `JsonValue; command "str_replace"constant` - - Command type identifier - - - `STR_REPLACE("str_replace")` - - - `String newStr` - - Text to replace with - - - `String oldStr` - - Text to search for and replace - - - `String path` - - Path to the file where text should be replaced - - - `class BetaMemoryTool20250818InsertCommand:` - - - `JsonValue; command "insert"constant` - - Command type identifier - - - `INSERT("insert")` - - - `long insertLine` - - Line number where text should be inserted - - - `String insertText` - - Text to insert at the specified line - - - `String path` - - Path to the file where text should be inserted - - - `class BetaMemoryTool20250818DeleteCommand:` - - - `JsonValue; command "delete"constant` - - Command type identifier - - - `DELETE("delete")` - - - `String path` - - Path to the file or directory to delete - - - `class BetaMemoryTool20250818RenameCommand:` - - - `JsonValue; command "rename"constant` - - Command type identifier - - - `RENAME("rename")` - - - `String newPath` - - New path for the file or directory - - - `String oldPath` - - Current path of the file or directory - -### Beta Memory Tool 20250818 Create Command - -- `class BetaMemoryTool20250818CreateCommand:` - - - `JsonValue; command "create"constant` - - Command type identifier - - - `CREATE("create")` - - - `String fileText` - - Content to write to the file - - - `String path` - - Path where the file should be created - -### Beta Memory Tool 20250818 Delete Command - -- `class BetaMemoryTool20250818DeleteCommand:` - - - `JsonValue; command "delete"constant` - - Command type identifier - - - `DELETE("delete")` - - - `String path` - - Path to the file or directory to delete - -### Beta Memory Tool 20250818 Insert Command - -- `class BetaMemoryTool20250818InsertCommand:` - - - `JsonValue; command "insert"constant` - - Command type identifier - - - `INSERT("insert")` - - - `long insertLine` - - Line number where text should be inserted - - - `String insertText` - - Text to insert at the specified line - - - `String path` - - Path to the file where text should be inserted - -### Beta Memory Tool 20250818 Rename Command - -- `class BetaMemoryTool20250818RenameCommand:` - - - `JsonValue; command "rename"constant` - - Command type identifier - - - `RENAME("rename")` - - - `String newPath` - - New path for the file or directory - - - `String oldPath` - - Current path of the file or directory - -### Beta Memory Tool 20250818 Str Replace Command - -- `class BetaMemoryTool20250818StrReplaceCommand:` - - - `JsonValue; command "str_replace"constant` - - Command type identifier - - - `STR_REPLACE("str_replace")` - - - `String newStr` - - Text to replace with - - - `String oldStr` - - Text to search for and replace - - - `String path` - - Path to the file where text should be replaced - -### Beta Memory Tool 20250818 View Command - -- `class BetaMemoryTool20250818ViewCommand:` - - - `JsonValue; command "view"constant` - - Command type identifier - - - `VIEW("view")` - - - `String path` - - Path to directory or file to view - - - `Optional> viewRange` - - Optional line range for viewing specific lines - -### Beta Message - -- `class BetaMessage:` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional container` - - Information about the container used in the request (for the code execution tool) - - - `String id` - - Identifier for the container used in this request - - - `LocalDateTime expiresAt` - - The time at which the container will expire. - - - `Optional> skills` - - Skills loaded in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `String version` - - Skill version or 'latest' for most recent version - - - `List content` - - Content generated by the model. - - This is an array of content blocks, each of which has a `type` that determines its shape. - - Example: - - ```json - [{"type": "text", "text": "Hi, I'm Claude."}] - ``` - - If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. - - For example, if the input `messages` were: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("} - ] - ``` - - Then the response `content` might be: - - ```json - [{"type": "text", "text": "B)"}] - ``` - - - `class BetaTextBlock:` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaThinkingBlock:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlock:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaServerToolUseBlock:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlock:` - - - `BetaWebSearchToolResultBlockContent content` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlock:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlock:` - - - `BetaCodeExecutionToolResultBlockContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `class BetaBashCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `class BetaTextEditorCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `class BetaToolSearchToolResultBlock:` - - - `Content content` - - - `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `class BetaMcpToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - The name of the MCP tool - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `class BetaMcpToolResultBlock:` - - - `Content content` - - - `String` - - - `List` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `boolean isError` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `class BetaContainerUploadBlock:` - - Response model for a file uploaded to the container. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `class BetaCompactionBlock:` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `Optional content` - - Summary of compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional contextManagement` - - Context management response. - - Information about context management strategies applied during the request. - - - `List appliedEdits` - - List of context management edits that were applied. - - - `class BetaClearToolUses20250919EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedToolUses` - - Number of tool uses that were cleared. - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - The type of context management edit applied. - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `class BetaClearThinking20251015EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedThinkingTurns` - - Number of thinking turns that were cleared. - - - `JsonValue; type "clear_thinking_20251015"constant` - - The type of context management edit applied. - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Model model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - - Most intelligent model for building agents and coding - - - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` - - Best combination of speed and intelligence - - - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_OPUS_4_5("claude-opus-4-5")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` - - High-performance model for agents and coding - - - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` - - High-performance model for agents and coding - - - `CLAUDE_OPUS_4_1("claude-opus-4-1")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_0("claude-opus-4-0")` - - Powerful model for complex tasks - - - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")` - - Powerful model for complex tasks - - - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")` - - High-performance model with extended thinking - - - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")` - - High-performance model with extended thinking - - - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")` - - Fast and cost-effective model - - - `JsonValue; role "assistant"constant` - - Conversational role of the generated message. - - This will always be `"assistant"`. - - - `ASSISTANT("assistant")` - - - `Optional stopDetails` - - Structured information about a refusal. - - - `Optional category` - - The policy category that triggered the refusal. - - `null` when the refusal doesn't map to a named category. - - - `CYBER("cyber")` - - - `BIO("bio")` - - - `Optional explanation` - - Human-readable explanation of the refusal. - - This text is not guaranteed to be stable. `null` when no explanation is available for the category. - - - `JsonValue; type "refusal"constant` - - - `REFUSAL("refusal")` - - - `Optional stopReason` - - The reason that we stopped. - - This may be one the following values: - - * `"end_turn"`: the model reached a natural stopping point - * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - * `"tool_use"`: the model invoked one or more tools - * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - * `"refusal"`: when streaming classifiers intervene to handle potential policy violations - - In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - - - `END_TURN("end_turn")` - - - `MAX_TOKENS("max_tokens")` - - - `STOP_SEQUENCE("stop_sequence")` - - - `TOOL_USE("tool_use")` - - - `PAUSE_TURN("pause_turn")` - - - `COMPACTION("compaction")` - - - `REFUSAL("refusal")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")` - - - `Optional stopSequence` - - Which custom stop sequence was generated, if any. - - This value will be a non-null string if one of your custom stop sequences was generated. - - - `JsonValue; type "message"constant` - - Object type. - - For Messages, this is always `"message"`. - - - `MESSAGE("message")` - - - `BetaUsage usage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `Optional cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `Optional cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `Optional inferenceGeo` - - The geographic region where inference was performed for this request. - - - `long inputTokens` - - The number of input tokens which were used. - - - `Optional> iterations` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - - - `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - - - `long outputTokens` - - The number of output tokens which were used. - - - `Optional serverToolUse` - - The number of server tool requests. - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - - - `Optional serviceTier` - - If the request used the priority, standard, or batch tier. - - - `STANDARD("standard")` - - - `PRIORITY("priority")` - - - `BATCH("batch")` - - - `Optional speed` - - The inference speed mode used for this request. - - - `STANDARD("standard")` - - - `FAST("fast")` - -### Beta Message Delta Usage - -- `class BetaMessageDeltaUsage:` - - - `Optional cacheCreationInputTokens` - - The cumulative number of input tokens used to create the cache entry. - - - `Optional cacheReadInputTokens` - - The cumulative number of input tokens read from the cache. - - - `Optional inputTokens` - - The cumulative number of input tokens which were used. - - - `Optional> iterations` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - - - `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - - - `long outputTokens` - - The cumulative number of output tokens which were used. - - - `Optional serverToolUse` - - The number of server tool requests. - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - -### Beta Message Iteration Usage - -- `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - -### Beta Message Param - -- `class BetaMessageParam:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaRequestDocumentBlock:` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `class BetaSearchResultBlockParam:` - - - `List content` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String source` - - - `String title` - - - `JsonValue; type "search_result"constant` - - - `SEARCH_RESULT("search_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `class BetaThinkingBlockParam:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlockParam:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaToolResultBlockParam:` - - - `String toolUseId` - - - `JsonValue; type "tool_result"constant` - - - `TOOL_RESULT("tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaSearchResultBlockParam:` - - - `List content` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String source` - - - `String title` - - - `JsonValue; type "search_result"constant` - - - `SEARCH_RESULT("search_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `class BetaRequestDocumentBlock:` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `class BetaToolReferenceBlockParam:` - - Tool reference block that can be included in tool_result content. - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional isError` - - - `class BetaServerToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlockParam:` - - - `BetaWebSearchToolResultBlockParamContent content` - - - `List` - - - `String encryptedContent` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `Optional pageAge` - - - `class BetaWebSearchToolRequestError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlockParam:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlockParam:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlockParam:` - - - `BetaRequestDocumentBlock content` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlockParam:` - - - `BetaCodeExecutionToolResultBlockParamContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultErrorParam:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlockParam:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaBashCodeExecutionToolResultBlockParam:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaTextEditorCodeExecutionToolResultBlockParam:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `Optional errorMessage` - - - `class BetaTextEditorCodeExecutionViewResultBlockParam:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `class BetaTextEditorCodeExecutionCreateResultBlockParam:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaToolSearchToolResultBlockParam:` - - - `Content content` - - - `class BetaToolSearchToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlockParam:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaMcpToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `String name` - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaRequestMcpToolResultBlockParam:` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional content` - - - `String` - - - `List` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `Optional isError` - - - `class BetaContainerUploadBlockParam:` - - A content block that represents a file to be uploaded to the container - Files uploaded via this block will be available in the container's input directory. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaCompactionBlockParam:` - - A compaction block containing summary of previous context. - - Users should round-trip these blocks from responses to subsequent requests - to maintain context across compaction boundaries. - - When content is None, the block represents a failed compaction. The server - treats these as no-ops. Empty string content is not allowed. - - - `Optional content` - - Summary of previously compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Role role` - - - `USER("user")` - - - `ASSISTANT("assistant")` - -### Beta Message Tokens Count - -- `class BetaMessageTokensCount:` - - - `Optional contextManagement` - - Information about context management applied to the message. - - - `long originalInputTokens` - - The original token count before context management was applied - - - `long inputTokens` - - The total number of tokens across the provided list of messages, system prompt, and tools. - -### Beta Metadata - -- `class BetaMetadata:` - - - `Optional userId` - - An external identifier for the user who is associated with the request. - - This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. - -### Beta Output Config - -- `class BetaOutputConfig:` - - - `Optional effort` - - All possible effort levels. - - - `LOW("low")` - - - `MEDIUM("medium")` - - - `HIGH("high")` - - - `MAX("max")` - - - `Optional format` - - A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - - - `Schema schema` - - The JSON schema of the format - - - `JsonValue; type "json_schema"constant` - - - `JSON_SCHEMA("json_schema")` - -### Beta Plain Text Source - -- `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - -### Beta Raw Content Block Delta - -- `class BetaRawContentBlockDelta: A class that can be one of several variants.union` - - - `class BetaTextDelta:` - - - `String text` - - - `JsonValue; type "text_delta"constant` - - - `TEXT_DELTA("text_delta")` - - - `class BetaInputJsonDelta:` - - - `String partialJson` - - - `JsonValue; type "input_json_delta"constant` - - - `INPUT_JSON_DELTA("input_json_delta")` - - - `class BetaCitationsDelta:` - - - `Citation citation` - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `JsonValue; type "citations_delta"constant` - - - `CITATIONS_DELTA("citations_delta")` - - - `class BetaThinkingDelta:` - - - `String thinking` - - - `JsonValue; type "thinking_delta"constant` - - - `THINKING_DELTA("thinking_delta")` - - - `class BetaSignatureDelta:` - - - `String signature` - - - `JsonValue; type "signature_delta"constant` - - - `SIGNATURE_DELTA("signature_delta")` - - - `class BetaCompactionContentBlockDelta:` - - - `Optional content` - - - `JsonValue; type "compaction_delta"constant` - - - `COMPACTION_DELTA("compaction_delta")` - -### Beta Raw Content Block Delta Event - -- `class BetaRawContentBlockDeltaEvent:` - - - `BetaRawContentBlockDelta delta` - - - `class BetaTextDelta:` - - - `String text` - - - `JsonValue; type "text_delta"constant` - - - `TEXT_DELTA("text_delta")` - - - `class BetaInputJsonDelta:` - - - `String partialJson` - - - `JsonValue; type "input_json_delta"constant` - - - `INPUT_JSON_DELTA("input_json_delta")` - - - `class BetaCitationsDelta:` - - - `Citation citation` - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `JsonValue; type "citations_delta"constant` - - - `CITATIONS_DELTA("citations_delta")` - - - `class BetaThinkingDelta:` - - - `String thinking` - - - `JsonValue; type "thinking_delta"constant` - - - `THINKING_DELTA("thinking_delta")` - - - `class BetaSignatureDelta:` - - - `String signature` - - - `JsonValue; type "signature_delta"constant` - - - `SIGNATURE_DELTA("signature_delta")` - - - `class BetaCompactionContentBlockDelta:` - - - `Optional content` - - - `JsonValue; type "compaction_delta"constant` - - - `COMPACTION_DELTA("compaction_delta")` - - - `long index` - - - `JsonValue; type "content_block_delta"constant` - - - `CONTENT_BLOCK_DELTA("content_block_delta")` - -### Beta Raw Content Block Start Event - -- `class BetaRawContentBlockStartEvent:` - - - `ContentBlock contentBlock` - - Response model for a file uploaded to the container. - - - `class BetaTextBlock:` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaThinkingBlock:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlock:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaServerToolUseBlock:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlock:` - - - `BetaWebSearchToolResultBlockContent content` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlock:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlock:` - - - `BetaCodeExecutionToolResultBlockContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `class BetaBashCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `class BetaTextEditorCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `class BetaToolSearchToolResultBlock:` - - - `Content content` - - - `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `class BetaMcpToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - The name of the MCP tool - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `class BetaMcpToolResultBlock:` - - - `Content content` - - - `String` - - - `List` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `boolean isError` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `class BetaContainerUploadBlock:` - - Response model for a file uploaded to the container. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `class BetaCompactionBlock:` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `Optional content` - - Summary of compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `long index` - - - `JsonValue; type "content_block_start"constant` - - - `CONTENT_BLOCK_START("content_block_start")` - -### Beta Raw Content Block Stop Event - -- `class BetaRawContentBlockStopEvent:` - - - `long index` - - - `JsonValue; type "content_block_stop"constant` - - - `CONTENT_BLOCK_STOP("content_block_stop")` - -### Beta Raw Message Delta Event - -- `class BetaRawMessageDeltaEvent:` - - - `Optional contextManagement` - - Information about context management strategies applied during the request - - - `List appliedEdits` - - List of context management edits that were applied. - - - `class BetaClearToolUses20250919EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedToolUses` - - Number of tool uses that were cleared. - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - The type of context management edit applied. - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `class BetaClearThinking20251015EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedThinkingTurns` - - Number of thinking turns that were cleared. - - - `JsonValue; type "clear_thinking_20251015"constant` - - The type of context management edit applied. - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Delta delta` - - - `Optional container` - - Information about the container used in the request (for the code execution tool) - - - `String id` - - Identifier for the container used in this request - - - `LocalDateTime expiresAt` - - The time at which the container will expire. - - - `Optional> skills` - - Skills loaded in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `String version` - - Skill version or 'latest' for most recent version - - - `Optional stopDetails` - - Structured information about a refusal. - - - `Optional category` - - The policy category that triggered the refusal. - - `null` when the refusal doesn't map to a named category. - - - `CYBER("cyber")` - - - `BIO("bio")` - - - `Optional explanation` - - Human-readable explanation of the refusal. - - This text is not guaranteed to be stable. `null` when no explanation is available for the category. - - - `JsonValue; type "refusal"constant` - - - `REFUSAL("refusal")` - - - `Optional stopReason` - - - `END_TURN("end_turn")` - - - `MAX_TOKENS("max_tokens")` - - - `STOP_SEQUENCE("stop_sequence")` - - - `TOOL_USE("tool_use")` - - - `PAUSE_TURN("pause_turn")` - - - `COMPACTION("compaction")` - - - `REFUSAL("refusal")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")` - - - `Optional stopSequence` - - - `JsonValue; type "message_delta"constant` - - - `MESSAGE_DELTA("message_delta")` - - - `BetaMessageDeltaUsage usage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `Optional cacheCreationInputTokens` - - The cumulative number of input tokens used to create the cache entry. - - - `Optional cacheReadInputTokens` - - The cumulative number of input tokens read from the cache. - - - `Optional inputTokens` - - The cumulative number of input tokens which were used. - - - `Optional> iterations` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - - - `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - - - `long outputTokens` - - The cumulative number of output tokens which were used. - - - `Optional serverToolUse` - - The number of server tool requests. - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - -### Beta Raw Message Start Event - -- `class BetaRawMessageStartEvent:` - - - `BetaMessage message` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional container` - - Information about the container used in the request (for the code execution tool) - - - `String id` - - Identifier for the container used in this request - - - `LocalDateTime expiresAt` - - The time at which the container will expire. - - - `Optional> skills` - - Skills loaded in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `String version` - - Skill version or 'latest' for most recent version - - - `List content` - - Content generated by the model. - - This is an array of content blocks, each of which has a `type` that determines its shape. - - Example: - - ```json - [{"type": "text", "text": "Hi, I'm Claude."}] - ``` - - If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. - - For example, if the input `messages` were: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("} - ] - ``` - - Then the response `content` might be: - - ```json - [{"type": "text", "text": "B)"}] - ``` - - - `class BetaTextBlock:` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaThinkingBlock:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlock:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaServerToolUseBlock:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlock:` - - - `BetaWebSearchToolResultBlockContent content` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlock:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlock:` - - - `BetaCodeExecutionToolResultBlockContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `class BetaBashCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `class BetaTextEditorCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `class BetaToolSearchToolResultBlock:` - - - `Content content` - - - `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `class BetaMcpToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - The name of the MCP tool - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `class BetaMcpToolResultBlock:` - - - `Content content` - - - `String` - - - `List` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `boolean isError` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `class BetaContainerUploadBlock:` - - Response model for a file uploaded to the container. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `class BetaCompactionBlock:` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `Optional content` - - Summary of compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional contextManagement` - - Context management response. - - Information about context management strategies applied during the request. - - - `List appliedEdits` - - List of context management edits that were applied. - - - `class BetaClearToolUses20250919EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedToolUses` - - Number of tool uses that were cleared. - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - The type of context management edit applied. - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `class BetaClearThinking20251015EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedThinkingTurns` - - Number of thinking turns that were cleared. - - - `JsonValue; type "clear_thinking_20251015"constant` - - The type of context management edit applied. - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Model model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - - Most intelligent model for building agents and coding - - - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` - - Best combination of speed and intelligence - - - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_OPUS_4_5("claude-opus-4-5")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` - - High-performance model for agents and coding - - - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` - - High-performance model for agents and coding - - - `CLAUDE_OPUS_4_1("claude-opus-4-1")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_0("claude-opus-4-0")` - - Powerful model for complex tasks - - - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")` - - Powerful model for complex tasks - - - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")` - - High-performance model with extended thinking - - - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")` - - High-performance model with extended thinking - - - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")` - - Fast and cost-effective model - - - `JsonValue; role "assistant"constant` - - Conversational role of the generated message. - - This will always be `"assistant"`. - - - `ASSISTANT("assistant")` - - - `Optional stopDetails` - - Structured information about a refusal. - - - `Optional category` - - The policy category that triggered the refusal. - - `null` when the refusal doesn't map to a named category. - - - `CYBER("cyber")` - - - `BIO("bio")` - - - `Optional explanation` - - Human-readable explanation of the refusal. - - This text is not guaranteed to be stable. `null` when no explanation is available for the category. - - - `JsonValue; type "refusal"constant` - - - `REFUSAL("refusal")` - - - `Optional stopReason` - - The reason that we stopped. - - This may be one the following values: - - * `"end_turn"`: the model reached a natural stopping point - * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - * `"tool_use"`: the model invoked one or more tools - * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - * `"refusal"`: when streaming classifiers intervene to handle potential policy violations - - In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - - - `END_TURN("end_turn")` - - - `MAX_TOKENS("max_tokens")` - - - `STOP_SEQUENCE("stop_sequence")` - - - `TOOL_USE("tool_use")` - - - `PAUSE_TURN("pause_turn")` - - - `COMPACTION("compaction")` - - - `REFUSAL("refusal")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")` - - - `Optional stopSequence` - - Which custom stop sequence was generated, if any. - - This value will be a non-null string if one of your custom stop sequences was generated. - - - `JsonValue; type "message"constant` - - Object type. - - For Messages, this is always `"message"`. - - - `MESSAGE("message")` - - - `BetaUsage usage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `Optional cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `Optional cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `Optional inferenceGeo` - - The geographic region where inference was performed for this request. - - - `long inputTokens` - - The number of input tokens which were used. - - - `Optional> iterations` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - - - `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - - - `long outputTokens` - - The number of output tokens which were used. - - - `Optional serverToolUse` - - The number of server tool requests. - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - - - `Optional serviceTier` - - If the request used the priority, standard, or batch tier. - - - `STANDARD("standard")` - - - `PRIORITY("priority")` - - - `BATCH("batch")` - - - `Optional speed` - - The inference speed mode used for this request. - - - `STANDARD("standard")` - - - `FAST("fast")` - - - `JsonValue; type "message_start"constant` - - - `MESSAGE_START("message_start")` - -### Beta Raw Message Stop Event - -- `class BetaRawMessageStopEvent:` - - - `JsonValue; type "message_stop"constant` - - - `MESSAGE_STOP("message_stop")` - -### Beta Raw Message Stream Event - -- `class BetaRawMessageStreamEvent: A class that can be one of several variants.union` - - - `class BetaRawMessageStartEvent:` - - - `BetaMessage message` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional container` - - Information about the container used in the request (for the code execution tool) - - - `String id` - - Identifier for the container used in this request - - - `LocalDateTime expiresAt` - - The time at which the container will expire. - - - `Optional> skills` - - Skills loaded in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `String version` - - Skill version or 'latest' for most recent version - - - `List content` - - Content generated by the model. - - This is an array of content blocks, each of which has a `type` that determines its shape. - - Example: - - ```json - [{"type": "text", "text": "Hi, I'm Claude."}] - ``` - - If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. - - For example, if the input `messages` were: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("} - ] - ``` - - Then the response `content` might be: - - ```json - [{"type": "text", "text": "B)"}] - ``` - - - `class BetaTextBlock:` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaThinkingBlock:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlock:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaServerToolUseBlock:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlock:` - - - `BetaWebSearchToolResultBlockContent content` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlock:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlock:` - - - `BetaCodeExecutionToolResultBlockContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `class BetaBashCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `class BetaTextEditorCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `class BetaToolSearchToolResultBlock:` - - - `Content content` - - - `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `class BetaMcpToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - The name of the MCP tool - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `class BetaMcpToolResultBlock:` - - - `Content content` - - - `String` - - - `List` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `boolean isError` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `class BetaContainerUploadBlock:` - - Response model for a file uploaded to the container. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `class BetaCompactionBlock:` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `Optional content` - - Summary of compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional contextManagement` - - Context management response. - - Information about context management strategies applied during the request. - - - `List appliedEdits` - - List of context management edits that were applied. - - - `class BetaClearToolUses20250919EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedToolUses` - - Number of tool uses that were cleared. - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - The type of context management edit applied. - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `class BetaClearThinking20251015EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedThinkingTurns` - - Number of thinking turns that were cleared. - - - `JsonValue; type "clear_thinking_20251015"constant` - - The type of context management edit applied. - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Model model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - - Most intelligent model for building agents and coding - - - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` - - Best combination of speed and intelligence - - - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_OPUS_4_5("claude-opus-4-5")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` - - High-performance model for agents and coding - - - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` - - High-performance model for agents and coding - - - `CLAUDE_OPUS_4_1("claude-opus-4-1")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_0("claude-opus-4-0")` - - Powerful model for complex tasks - - - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")` - - Powerful model for complex tasks - - - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")` - - High-performance model with extended thinking - - - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")` - - High-performance model with extended thinking - - - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")` - - Fast and cost-effective model - - - `JsonValue; role "assistant"constant` - - Conversational role of the generated message. - - This will always be `"assistant"`. - - - `ASSISTANT("assistant")` - - - `Optional stopDetails` - - Structured information about a refusal. - - - `Optional category` - - The policy category that triggered the refusal. - - `null` when the refusal doesn't map to a named category. - - - `CYBER("cyber")` - - - `BIO("bio")` - - - `Optional explanation` - - Human-readable explanation of the refusal. - - This text is not guaranteed to be stable. `null` when no explanation is available for the category. - - - `JsonValue; type "refusal"constant` - - - `REFUSAL("refusal")` - - - `Optional stopReason` - - The reason that we stopped. - - This may be one the following values: - - * `"end_turn"`: the model reached a natural stopping point - * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - * `"tool_use"`: the model invoked one or more tools - * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - * `"refusal"`: when streaming classifiers intervene to handle potential policy violations - - In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - - - `END_TURN("end_turn")` - - - `MAX_TOKENS("max_tokens")` - - - `STOP_SEQUENCE("stop_sequence")` - - - `TOOL_USE("tool_use")` - - - `PAUSE_TURN("pause_turn")` - - - `COMPACTION("compaction")` - - - `REFUSAL("refusal")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")` - - - `Optional stopSequence` - - Which custom stop sequence was generated, if any. - - This value will be a non-null string if one of your custom stop sequences was generated. - - - `JsonValue; type "message"constant` - - Object type. - - For Messages, this is always `"message"`. - - - `MESSAGE("message")` - - - `BetaUsage usage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `Optional cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `Optional cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `Optional inferenceGeo` - - The geographic region where inference was performed for this request. - - - `long inputTokens` - - The number of input tokens which were used. - - - `Optional> iterations` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - - - `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - - - `long outputTokens` - - The number of output tokens which were used. - - - `Optional serverToolUse` - - The number of server tool requests. - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - - - `Optional serviceTier` - - If the request used the priority, standard, or batch tier. - - - `STANDARD("standard")` - - - `PRIORITY("priority")` - - - `BATCH("batch")` - - - `Optional speed` - - The inference speed mode used for this request. - - - `STANDARD("standard")` - - - `FAST("fast")` - - - `JsonValue; type "message_start"constant` - - - `MESSAGE_START("message_start")` - - - `class BetaRawMessageDeltaEvent:` - - - `Optional contextManagement` - - Information about context management strategies applied during the request - - - `List appliedEdits` - - List of context management edits that were applied. - - - `class BetaClearToolUses20250919EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedToolUses` - - Number of tool uses that were cleared. - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - The type of context management edit applied. - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `class BetaClearThinking20251015EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedThinkingTurns` - - Number of thinking turns that were cleared. - - - `JsonValue; type "clear_thinking_20251015"constant` - - The type of context management edit applied. - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Delta delta` - - - `Optional container` - - Information about the container used in the request (for the code execution tool) - - - `String id` - - Identifier for the container used in this request - - - `LocalDateTime expiresAt` - - The time at which the container will expire. - - - `Optional> skills` - - Skills loaded in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `String version` - - Skill version or 'latest' for most recent version - - - `Optional stopDetails` - - Structured information about a refusal. - - - `Optional category` - - The policy category that triggered the refusal. - - `null` when the refusal doesn't map to a named category. - - - `CYBER("cyber")` - - - `BIO("bio")` - - - `Optional explanation` - - Human-readable explanation of the refusal. - - This text is not guaranteed to be stable. `null` when no explanation is available for the category. - - - `JsonValue; type "refusal"constant` - - - `REFUSAL("refusal")` - - - `Optional stopReason` - - - `END_TURN("end_turn")` - - - `MAX_TOKENS("max_tokens")` - - - `STOP_SEQUENCE("stop_sequence")` - - - `TOOL_USE("tool_use")` - - - `PAUSE_TURN("pause_turn")` - - - `COMPACTION("compaction")` - - - `REFUSAL("refusal")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")` - - - `Optional stopSequence` - - - `JsonValue; type "message_delta"constant` - - - `MESSAGE_DELTA("message_delta")` - - - `BetaMessageDeltaUsage usage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `Optional cacheCreationInputTokens` - - The cumulative number of input tokens used to create the cache entry. - - - `Optional cacheReadInputTokens` - - The cumulative number of input tokens read from the cache. - - - `Optional inputTokens` - - The cumulative number of input tokens which were used. - - - `Optional> iterations` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - - - `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - - - `long outputTokens` - - The cumulative number of output tokens which were used. - - - `Optional serverToolUse` - - The number of server tool requests. - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - - - `class BetaRawMessageStopEvent:` - - - `JsonValue; type "message_stop"constant` - - - `MESSAGE_STOP("message_stop")` - - - `class BetaRawContentBlockStartEvent:` - - - `ContentBlock contentBlock` - - Response model for a file uploaded to the container. - - - `class BetaTextBlock:` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaThinkingBlock:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlock:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaServerToolUseBlock:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlock:` - - - `BetaWebSearchToolResultBlockContent content` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlock:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlock:` - - - `BetaCodeExecutionToolResultBlockContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `class BetaBashCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `class BetaTextEditorCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `class BetaToolSearchToolResultBlock:` - - - `Content content` - - - `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `class BetaMcpToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - The name of the MCP tool - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `class BetaMcpToolResultBlock:` - - - `Content content` - - - `String` - - - `List` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `boolean isError` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `class BetaContainerUploadBlock:` - - Response model for a file uploaded to the container. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `class BetaCompactionBlock:` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `Optional content` - - Summary of compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `long index` - - - `JsonValue; type "content_block_start"constant` - - - `CONTENT_BLOCK_START("content_block_start")` - - - `class BetaRawContentBlockDeltaEvent:` - - - `BetaRawContentBlockDelta delta` - - - `class BetaTextDelta:` - - - `String text` - - - `JsonValue; type "text_delta"constant` - - - `TEXT_DELTA("text_delta")` - - - `class BetaInputJsonDelta:` - - - `String partialJson` - - - `JsonValue; type "input_json_delta"constant` - - - `INPUT_JSON_DELTA("input_json_delta")` - - - `class BetaCitationsDelta:` - - - `Citation citation` - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `JsonValue; type "citations_delta"constant` - - - `CITATIONS_DELTA("citations_delta")` - - - `class BetaThinkingDelta:` - - - `String thinking` - - - `JsonValue; type "thinking_delta"constant` - - - `THINKING_DELTA("thinking_delta")` - - - `class BetaSignatureDelta:` - - - `String signature` - - - `JsonValue; type "signature_delta"constant` - - - `SIGNATURE_DELTA("signature_delta")` - - - `class BetaCompactionContentBlockDelta:` - - - `Optional content` - - - `JsonValue; type "compaction_delta"constant` - - - `COMPACTION_DELTA("compaction_delta")` - - - `long index` - - - `JsonValue; type "content_block_delta"constant` - - - `CONTENT_BLOCK_DELTA("content_block_delta")` - - - `class BetaRawContentBlockStopEvent:` - - - `long index` - - - `JsonValue; type "content_block_stop"constant` - - - `CONTENT_BLOCK_STOP("content_block_stop")` - -### Beta Redacted Thinking Block - -- `class BetaRedactedThinkingBlock:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - -### Beta Redacted Thinking Block Param - -- `class BetaRedactedThinkingBlockParam:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - -### Beta Refusal Stop Details - -- `class BetaRefusalStopDetails:` - - Structured information about a refusal. - - - `Optional category` - - The policy category that triggered the refusal. - - `null` when the refusal doesn't map to a named category. - - - `CYBER("cyber")` - - - `BIO("bio")` - - - `Optional explanation` - - Human-readable explanation of the refusal. - - This text is not guaranteed to be stable. `null` when no explanation is available for the category. - - - `JsonValue; type "refusal"constant` - - - `REFUSAL("refusal")` - -### Beta Request Document Block - -- `class BetaRequestDocumentBlock:` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - -### Beta Request MCP Server Tool Configuration - -- `class BetaRequestMcpServerToolConfiguration:` - - - `Optional> allowedTools` - - - `Optional enabled` - -### Beta Request MCP Server URL Definition - -- `class BetaRequestMcpServerUrlDefinition:` - - - `String name` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `Optional authorizationToken` - - - `Optional toolConfiguration` - - - `Optional> allowedTools` - - - `Optional enabled` - -### Beta Request MCP Tool Result Block Param - -- `class BetaRequestMcpToolResultBlockParam:` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional content` - - - `String` - - - `List` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `Optional isError` - -### Beta Search Result Block Param - -- `class BetaSearchResultBlockParam:` - - - `List content` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String source` - - - `String title` - - - `JsonValue; type "search_result"constant` - - - `SEARCH_RESULT("search_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - -### Beta Server Tool Caller - -- `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - -### Beta Server Tool Caller 20260120 - -- `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - -### Beta Server Tool Usage - -- `class BetaServerToolUsage:` - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - -### Beta Server Tool Use Block - -- `class BetaServerToolUseBlock:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - -### Beta Server Tool Use Block Param - -- `class BetaServerToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - -### Beta Signature Delta - -- `class BetaSignatureDelta:` - - - `String signature` - - - `JsonValue; type "signature_delta"constant` - - - `SIGNATURE_DELTA("signature_delta")` - -### Beta Skill - -- `class BetaSkill:` - - A skill that was loaded in a container (response model). - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `String version` - - Skill version or 'latest' for most recent version - -### Beta Skill Params - -- `class BetaSkillParams:` - - Specification for a skill to be loaded in a container (request model). - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `Optional version` - - Skill version or 'latest' for most recent version - -### Beta Stop Reason - -- `enum BetaStopReason:` - - - `END_TURN("end_turn")` - - - `MAX_TOKENS("max_tokens")` - - - `STOP_SEQUENCE("stop_sequence")` - - - `TOOL_USE("tool_use")` - - - `PAUSE_TURN("pause_turn")` - - - `COMPACTION("compaction")` - - - `REFUSAL("refusal")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")` - -### Beta Text Block - -- `class BetaTextBlock:` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - -### Beta Text Block Param - -- `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - -### Beta Text Citation - -- `class BetaTextCitation: A class that can be one of several variants.union` - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - -### Beta Text Citation Param - -- `class BetaTextCitationParam: A class that can be one of several variants.union` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - -### Beta Text Delta - -- `class BetaTextDelta:` - - - `String text` - - - `JsonValue; type "text_delta"constant` - - - `TEXT_DELTA("text_delta")` - -### Beta Text Editor Code Execution Create Result Block - -- `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - -### Beta Text Editor Code Execution Create Result Block Param - -- `class BetaTextEditorCodeExecutionCreateResultBlockParam:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - -### Beta Text Editor Code Execution Str Replace Result Block - -- `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - -### Beta Text Editor Code Execution Str Replace Result Block Param - -- `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - -### Beta Text Editor Code Execution Tool Result Block - -- `class BetaTextEditorCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - -### Beta Text Editor Code Execution Tool Result Block Param - -- `class BetaTextEditorCodeExecutionToolResultBlockParam:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `Optional errorMessage` - - - `class BetaTextEditorCodeExecutionViewResultBlockParam:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `class BetaTextEditorCodeExecutionCreateResultBlockParam:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - -### Beta Text Editor Code Execution Tool Result Error - -- `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - -### Beta Text Editor Code Execution Tool Result Error Param - -- `class BetaTextEditorCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `Optional errorMessage` - -### Beta Text Editor Code Execution View Result Block - -- `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - -### Beta Text Editor Code Execution View Result Block Param - -- `class BetaTextEditorCodeExecutionViewResultBlockParam:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - -### Beta Thinking Block - -- `class BetaThinkingBlock:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - -### Beta Thinking Block Param - -- `class BetaThinkingBlockParam:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - -### Beta Thinking Config Adaptive - -- `class BetaThinkingConfigAdaptive:` - - - `JsonValue; type "adaptive"constant` - - - `ADAPTIVE("adaptive")` - - - `Optional display` - - Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - - - `SUMMARIZED("summarized")` - - - `OMITTED("omitted")` - -### Beta Thinking Config Disabled - -- `class BetaThinkingConfigDisabled:` - - - `JsonValue; type "disabled"constant` - - - `DISABLED("disabled")` - -### Beta Thinking Config Enabled - -- `class BetaThinkingConfigEnabled:` - - - `long budgetTokens` - - Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. - - Must be ≥1024 and less than `max_tokens`. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `JsonValue; type "enabled"constant` - - - `ENABLED("enabled")` - - - `Optional display` - - Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - - - `SUMMARIZED("summarized")` - - - `OMITTED("omitted")` - -### Beta Thinking Config Param - -- `class BetaThinkingConfigParam: A class that can be one of several variants.union` - - Configuration for enabling Claude's extended thinking. - - When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `class BetaThinkingConfigEnabled:` - - - `long budgetTokens` - - Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. - - Must be ≥1024 and less than `max_tokens`. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `JsonValue; type "enabled"constant` - - - `ENABLED("enabled")` - - - `Optional display` - - Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - - - `SUMMARIZED("summarized")` - - - `OMITTED("omitted")` - - - `class BetaThinkingConfigDisabled:` - - - `JsonValue; type "disabled"constant` - - - `DISABLED("disabled")` - - - `class BetaThinkingConfigAdaptive:` - - - `JsonValue; type "adaptive"constant` - - - `ADAPTIVE("adaptive")` - - - `Optional display` - - Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - - - `SUMMARIZED("summarized")` - - - `OMITTED("omitted")` - -### Beta Thinking Delta - -- `class BetaThinkingDelta:` - - - `String thinking` - - - `JsonValue; type "thinking_delta"constant` - - - `THINKING_DELTA("thinking_delta")` - -### Beta Thinking Turns - -- `class BetaThinkingTurns:` - - - `JsonValue; type "thinking_turns"constant` - - - `THINKING_TURNS("thinking_turns")` - - - `long value` - -### Beta Tool - -- `class BetaTool:` - - - `InputSchema inputSchema` - - [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. - - This defines the shape of the `input` that your tool accepts and that the model will produce. - - - `JsonValue; type "object"constant` - - - `OBJECT("object")` - - - `Optional properties` - - - `Optional> required` - - - `String name` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional description` - - Description of what this tool does. - - Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - - - `Optional eagerInputStreaming` - - Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional type` - - - `CUSTOM("custom")` - -### Beta Tool Bash 20241022 - -- `class BetaToolBash20241022:` - - - `JsonValue; name "bash"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `BASH("bash")` - - - `JsonValue; type "bash_20241022"constant` - - - `BASH_20241022("bash_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Tool Bash 20250124 - -- `class BetaToolBash20250124:` - - - `JsonValue; name "bash"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `BASH("bash")` - - - `JsonValue; type "bash_20250124"constant` - - - `BASH_20250124("bash_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Tool Choice - -- `class BetaToolChoice: A class that can be one of several variants.union` - - How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. - - - `class BetaToolChoiceAuto:` - - The model will automatically decide whether to use tools. - - - `JsonValue; type "auto"constant` - - - `AUTO("auto")` - - - `Optional disableParallelToolUse` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output at most one tool use. - - - `class BetaToolChoiceAny:` - - The model will use any available tools. - - - `JsonValue; type "any"constant` - - - `ANY("any")` - - - `Optional disableParallelToolUse` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - - `class BetaToolChoiceTool:` - - The model will use the specified tool with `tool_choice.name`. - - - `String name` - - The name of the tool to use. - - - `JsonValue; type "tool"constant` - - - `TOOL("tool")` - - - `Optional disableParallelToolUse` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - - `class BetaToolChoiceNone:` - - The model will not be allowed to use tools. - - - `JsonValue; type "none"constant` - - - `NONE("none")` - -### Beta Tool Choice Any - -- `class BetaToolChoiceAny:` - - The model will use any available tools. - - - `JsonValue; type "any"constant` - - - `ANY("any")` - - - `Optional disableParallelToolUse` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - -### Beta Tool Choice Auto - -- `class BetaToolChoiceAuto:` - - The model will automatically decide whether to use tools. - - - `JsonValue; type "auto"constant` - - - `AUTO("auto")` - - - `Optional disableParallelToolUse` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output at most one tool use. - -### Beta Tool Choice None - -- `class BetaToolChoiceNone:` - - The model will not be allowed to use tools. - - - `JsonValue; type "none"constant` - - - `NONE("none")` - -### Beta Tool Choice Tool - -- `class BetaToolChoiceTool:` - - The model will use the specified tool with `tool_choice.name`. - - - `String name` - - The name of the tool to use. - - - `JsonValue; type "tool"constant` - - - `TOOL("tool")` - - - `Optional disableParallelToolUse` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - -### Beta Tool Computer Use 20241022 - -- `class BetaToolComputerUse20241022:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20241022"constant` - - - `COMPUTER_20241022("computer_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Tool Computer Use 20250124 - -- `class BetaToolComputerUse20250124:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20250124"constant` - - - `COMPUTER_20250124("computer_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Tool Computer Use 20251124 - -- `class BetaToolComputerUse20251124:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20251124"constant` - - - `COMPUTER_20251124("computer_20251124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional enableZoom` - - Whether to enable an action to take a zoomed-in screenshot of the screen. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Tool Reference Block - -- `class BetaToolReferenceBlock:` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - -### Beta Tool Reference Block Param - -- `class BetaToolReferenceBlockParam:` - - Tool reference block that can be included in tool_result content. - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - -### Beta Tool Result Block Param - -- `class BetaToolResultBlockParam:` - - - `String toolUseId` - - - `JsonValue; type "tool_result"constant` - - - `TOOL_RESULT("tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaSearchResultBlockParam:` - - - `List content` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String source` - - - `String title` - - - `JsonValue; type "search_result"constant` - - - `SEARCH_RESULT("search_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `class BetaRequestDocumentBlock:` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `class BetaToolReferenceBlockParam:` - - Tool reference block that can be included in tool_result content. - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional isError` - -### Beta Tool Search Tool Bm25 20251119 - -- `class BetaToolSearchToolBm25_20251119:` - - - `JsonValue; name "tool_search_tool_bm25"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `Type type` - - - `TOOL_SEARCH_TOOL_BM25_20251119("tool_search_tool_bm25_20251119")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Tool Search Tool Regex 20251119 - -- `class BetaToolSearchToolRegex20251119:` - - - `JsonValue; name "tool_search_tool_regex"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `Type type` - - - `TOOL_SEARCH_TOOL_REGEX_20251119("tool_search_tool_regex_20251119")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Tool Search Tool Result Block - -- `class BetaToolSearchToolResultBlock:` - - - `Content content` - - - `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - -### Beta Tool Search Tool Result Block Param - -- `class BetaToolSearchToolResultBlockParam:` - - - `Content content` - - - `class BetaToolSearchToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlockParam:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - -### Beta Tool Search Tool Result Error - -- `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - -### Beta Tool Search Tool Result Error Param - -- `class BetaToolSearchToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - -### Beta Tool Search Tool Search Result Block - -- `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - -### Beta Tool Search Tool Search Result Block Param - -- `class BetaToolSearchToolSearchResultBlockParam:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - -### Beta Tool Text Editor 20241022 - -- `class BetaToolTextEditor20241022:` - - - `JsonValue; name "str_replace_editor"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_EDITOR("str_replace_editor")` - - - `JsonValue; type "text_editor_20241022"constant` - - - `TEXT_EDITOR_20241022("text_editor_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Tool Text Editor 20250124 - -- `class BetaToolTextEditor20250124:` - - - `JsonValue; name "str_replace_editor"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_EDITOR("str_replace_editor")` - - - `JsonValue; type "text_editor_20250124"constant` - - - `TEXT_EDITOR_20250124("text_editor_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Tool Text Editor 20250429 - -- `class BetaToolTextEditor20250429:` - - - `JsonValue; name "str_replace_based_edit_tool"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")` - - - `JsonValue; type "text_editor_20250429"constant` - - - `TEXT_EDITOR_20250429("text_editor_20250429")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Tool Text Editor 20250728 - -- `class BetaToolTextEditor20250728:` - - - `JsonValue; name "str_replace_based_edit_tool"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")` - - - `JsonValue; type "text_editor_20250728"constant` - - - `TEXT_EDITOR_20250728("text_editor_20250728")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional maxCharacters` - - Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Tool Union - -- `class BetaToolUnion: A class that can be one of several variants.union` - - Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - - - `class BetaTool:` - - - `InputSchema inputSchema` - - [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. - - This defines the shape of the `input` that your tool accepts and that the model will produce. - - - `JsonValue; type "object"constant` - - - `OBJECT("object")` - - - `Optional properties` - - - `Optional> required` - - - `String name` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional description` - - Description of what this tool does. - - Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - - - `Optional eagerInputStreaming` - - Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional type` - - - `CUSTOM("custom")` - - - `class BetaToolBash20241022:` - - - `JsonValue; name "bash"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `BASH("bash")` - - - `JsonValue; type "bash_20241022"constant` - - - `BASH_20241022("bash_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolBash20250124:` - - - `JsonValue; name "bash"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `BASH("bash")` - - - `JsonValue; type "bash_20250124"constant` - - - `BASH_20250124("bash_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaCodeExecutionTool20250522:` - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20250522"constant` - - - `CODE_EXECUTION_20250522("code_execution_20250522")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaCodeExecutionTool20250825:` - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaCodeExecutionTool20260120:` - - Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolComputerUse20241022:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20241022"constant` - - - `COMPUTER_20241022("computer_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaMemoryTool20250818:` - - - `JsonValue; name "memory"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `MEMORY("memory")` - - - `JsonValue; type "memory_20250818"constant` - - - `MEMORY_20250818("memory_20250818")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolComputerUse20250124:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20250124"constant` - - - `COMPUTER_20250124("computer_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20241022:` - - - `JsonValue; name "str_replace_editor"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_EDITOR("str_replace_editor")` - - - `JsonValue; type "text_editor_20241022"constant` - - - `TEXT_EDITOR_20241022("text_editor_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolComputerUse20251124:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20251124"constant` - - - `COMPUTER_20251124("computer_20251124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional enableZoom` - - Whether to enable an action to take a zoomed-in screenshot of the screen. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20250124:` - - - `JsonValue; name "str_replace_editor"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_EDITOR("str_replace_editor")` - - - `JsonValue; type "text_editor_20250124"constant` - - - `TEXT_EDITOR_20250124("text_editor_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20250429:` - - - `JsonValue; name "str_replace_based_edit_tool"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")` - - - `JsonValue; type "text_editor_20250429"constant` - - - `TEXT_EDITOR_20250429("text_editor_20250429")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20250728:` - - - `JsonValue; name "str_replace_based_edit_tool"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")` - - - `JsonValue; type "text_editor_20250728"constant` - - - `TEXT_EDITOR_20250728("text_editor_20250728")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional maxCharacters` - - Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaWebSearchTool20250305:` - - - `JsonValue; name "web_search"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_SEARCH("web_search")` - - - `JsonValue; type "web_search_20250305"constant` - - - `WEB_SEARCH_20250305("web_search_20250305")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `Optional> blockedDomains` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional userLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `JsonValue; type "approximate"constant` - - - `APPROXIMATE("approximate")` - - - `Optional city` - - The city of the user. - - - `Optional country` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `Optional region` - - The region of the user. - - - `Optional timezone` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `class BetaWebFetchTool20250910:` - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20250910"constant` - - - `WEB_FETCH_20250910("web_fetch_20250910")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaWebSearchTool20260209:` - - - `JsonValue; name "web_search"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_SEARCH("web_search")` - - - `JsonValue; type "web_search_20260209"constant` - - - `WEB_SEARCH_20260209("web_search_20260209")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `Optional> blockedDomains` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional userLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `JsonValue; type "approximate"constant` - - - `APPROXIMATE("approximate")` - - - `Optional city` - - The city of the user. - - - `Optional country` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `Optional region` - - The region of the user. - - - `Optional timezone` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `class BetaWebFetchTool20260209:` - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20260209"constant` - - - `WEB_FETCH_20260209("web_fetch_20260209")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaWebFetchTool20260309:` - - Web fetch tool with use_cache parameter for bypassing cached content. - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20260309"constant` - - - `WEB_FETCH_20260309("web_fetch_20260309")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional useCache` - - Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - - - `class BetaToolSearchToolBm25_20251119:` - - - `JsonValue; name "tool_search_tool_bm25"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `Type type` - - - `TOOL_SEARCH_TOOL_BM25_20251119("tool_search_tool_bm25_20251119")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolSearchToolRegex20251119:` - - - `JsonValue; name "tool_search_tool_regex"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `Type type` - - - `TOOL_SEARCH_TOOL_REGEX_20251119("tool_search_tool_regex_20251119")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaMcpToolset:` - - Configuration for a group of tools from an MCP server. - - Allows configuring enabled status and defer_loading for all tools - from an MCP server, with optional per-tool overrides. - - - `String mcpServerName` - - Name of the MCP server to configure tools for - - - `JsonValue; type "mcp_toolset"constant` - - - `MCP_TOOLSET("mcp_toolset")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional configs` - - Configuration overrides for specific tools, keyed by tool name - - - `Optional deferLoading` - - - `Optional enabled` - - - `Optional defaultConfig` - - Default configuration applied to all tools from this server - - - `Optional deferLoading` - - - `Optional enabled` - -### Beta Tool Use Block - -- `class BetaToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - -### Beta Tool Use Block Param - -- `class BetaToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - -### Beta Tool Uses Keep - -- `class BetaToolUsesKeep:` - - - `JsonValue; type "tool_uses"constant` - - - `TOOL_USES("tool_uses")` - - - `long value` - -### Beta Tool Uses Trigger - -- `class BetaToolUsesTrigger:` - - - `JsonValue; type "tool_uses"constant` - - - `TOOL_USES("tool_uses")` - - - `long value` - -### Beta URL Image Source - -- `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - -### Beta URL PDF Source - -- `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - -### Beta Usage - -- `class BetaUsage:` - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `Optional cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `Optional cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `Optional inferenceGeo` - - The geographic region where inference was performed for this request. - - - `long inputTokens` - - The number of input tokens which were used. - - - `Optional> iterations` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - - - `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - - - `long outputTokens` - - The number of output tokens which were used. - - - `Optional serverToolUse` - - The number of server tool requests. - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - - - `Optional serviceTier` - - If the request used the priority, standard, or batch tier. - - - `STANDARD("standard")` - - - `PRIORITY("priority")` - - - `BATCH("batch")` - - - `Optional speed` - - The inference speed mode used for this request. - - - `STANDARD("standard")` - - - `FAST("fast")` - -### Beta User Location - -- `class BetaUserLocation:` - - - `JsonValue; type "approximate"constant` - - - `APPROXIMATE("approximate")` - - - `Optional city` - - The city of the user. - - - `Optional country` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `Optional region` - - The region of the user. - - - `Optional timezone` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - -### Beta Web Fetch Block - -- `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - -### Beta Web Fetch Block Param - -- `class BetaWebFetchBlockParam:` - - - `BetaRequestDocumentBlock content` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - -### Beta Web Fetch Tool 20250910 - -- `class BetaWebFetchTool20250910:` - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20250910"constant` - - - `WEB_FETCH_20250910("web_fetch_20250910")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Web Fetch Tool 20260209 - -- `class BetaWebFetchTool20260209:` - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20260209"constant` - - - `WEB_FETCH_20260209("web_fetch_20260209")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - -### Beta Web Fetch Tool 20260309 - -- `class BetaWebFetchTool20260309:` - - Web fetch tool with use_cache parameter for bypassing cached content. - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20260309"constant` - - - `WEB_FETCH_20260309("web_fetch_20260309")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional useCache` - - Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - -### Beta Web Fetch Tool Result Block - -- `class BetaWebFetchToolResultBlock:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - -### Beta Web Fetch Tool Result Block Param - -- `class BetaWebFetchToolResultBlockParam:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlockParam:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlockParam:` - - - `BetaRequestDocumentBlock content` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - -### Beta Web Fetch Tool Result Error Block - -- `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - -### Beta Web Fetch Tool Result Error Block Param - -- `class BetaWebFetchToolResultErrorBlockParam:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - -### Beta Web Fetch Tool Result Error Code - -- `enum BetaWebFetchToolResultErrorCode:` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - -### Beta Web Search Result Block - -- `class BetaWebSearchResultBlock:` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - -### Beta Web Search Result Block Param - -- `class BetaWebSearchResultBlockParam:` - - - `String encryptedContent` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `Optional pageAge` - -### Beta Web Search Tool 20250305 - -- `class BetaWebSearchTool20250305:` - - - `JsonValue; name "web_search"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_SEARCH("web_search")` - - - `JsonValue; type "web_search_20250305"constant` - - - `WEB_SEARCH_20250305("web_search_20250305")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `Optional> blockedDomains` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional userLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `JsonValue; type "approximate"constant` - - - `APPROXIMATE("approximate")` - - - `Optional city` - - The city of the user. - - - `Optional country` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `Optional region` - - The region of the user. - - - `Optional timezone` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - -### Beta Web Search Tool 20260209 - -- `class BetaWebSearchTool20260209:` - - - `JsonValue; name "web_search"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_SEARCH("web_search")` - - - `JsonValue; type "web_search_20260209"constant` - - - `WEB_SEARCH_20260209("web_search_20260209")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `Optional> blockedDomains` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional userLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `JsonValue; type "approximate"constant` - - - `APPROXIMATE("approximate")` - - - `Optional city` - - The city of the user. - - - `Optional country` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `Optional region` - - The region of the user. - - - `Optional timezone` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - -### Beta Web Search Tool Request Error - -- `class BetaWebSearchToolRequestError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - -### Beta Web Search Tool Result Block - -- `class BetaWebSearchToolResultBlock:` - - - `BetaWebSearchToolResultBlockContent content` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - -### Beta Web Search Tool Result Block Content - -- `class BetaWebSearchToolResultBlockContent: A class that can be one of several variants.union` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - -### Beta Web Search Tool Result Block Param - -- `class BetaWebSearchToolResultBlockParam:` - - - `BetaWebSearchToolResultBlockParamContent content` - - - `List` - - - `String encryptedContent` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `Optional pageAge` - - - `class BetaWebSearchToolRequestError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - -### Beta Web Search Tool Result Block Param Content - -- `class BetaWebSearchToolResultBlockParamContent: A class that can be one of several variants.union` - - - `List` - - - `String encryptedContent` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `Optional pageAge` - - - `class BetaWebSearchToolRequestError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - -### Beta Web Search Tool Result Error - -- `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - -### Beta Web Search Tool Result Error Code - -- `enum BetaWebSearchToolResultErrorCode:` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - -# Batches - -## Create - -`BetaMessageBatch beta().messages().batches().create(BatchCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - -**post** `/v1/messages/batches` - -Send a batch of Message creation requests. - -The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete. - -Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) - -### Parameters - -- `BatchCreateParams params` - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - - `List requests` - - List of requests for prompt completion. Each is an individual request to create a Message. - - - `String customId` - - Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. - - Must be unique for each request within the Message Batch. - - - `Params params` - - Messages API creation parameters for the individual request. - - See the [Messages API reference](https://docs.claude.com/en/api/messages) for full documentation on available parameters. - - - `long maxTokens` - - The maximum number of tokens to generate before stopping. - - Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. - - Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. - - - `List messages` - - Input messages. - - Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. - - Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. - - If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. - - Example with a single `user` message: - - ```json - [{"role": "user", "content": "Hello, Claude"}] - ``` - - Example with multiple conversational turns: - - ```json - [ - {"role": "user", "content": "Hello there."}, - {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, - {"role": "user", "content": "Can you explain LLMs in plain English?"}, - ] - ``` - - Example with a partially-filled response from Claude: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("}, - ] - ``` - - Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: - - ```json - {"role": "user", "content": "Hello, Claude"} - ``` - - ```json - {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} - ``` - - See [input examples](https://docs.claude.com/en/api/messages-examples). - - Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. - - There is a limit of 100,000 messages in a single request. - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaRequestDocumentBlock:` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `class BetaSearchResultBlockParam:` - - - `List content` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String source` - - - `String title` - - - `JsonValue; type "search_result"constant` - - - `SEARCH_RESULT("search_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `class BetaThinkingBlockParam:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlockParam:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaToolResultBlockParam:` - - - `String toolUseId` - - - `JsonValue; type "tool_result"constant` - - - `TOOL_RESULT("tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaSearchResultBlockParam:` - - - `List content` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String source` - - - `String title` - - - `JsonValue; type "search_result"constant` - - - `SEARCH_RESULT("search_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `class BetaRequestDocumentBlock:` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `class BetaToolReferenceBlockParam:` - - Tool reference block that can be included in tool_result content. - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional isError` - - - `class BetaServerToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlockParam:` - - - `BetaWebSearchToolResultBlockParamContent content` - - - `List` - - - `String encryptedContent` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `Optional pageAge` - - - `class BetaWebSearchToolRequestError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlockParam:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlockParam:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlockParam:` - - - `BetaRequestDocumentBlock content` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaContentBlockSource:` - - - `Content content` - - - `String` - - - `List` - - - `class BetaTextBlockParam:` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `class BetaImageBlockParam:` - - - `Source source` - - - `class BetaBase64ImageSource:` - - - `String data` - - - `MediaType mediaType` - - - `IMAGE_JPEG("image/jpeg")` - - - `IMAGE_PNG("image/png")` - - - `IMAGE_GIF("image/gif")` - - - `IMAGE_WEBP("image/webp")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaUrlImageSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileImageSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "image"constant` - - - `IMAGE("image")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "content"constant` - - - `CONTENT("content")` - - - `class BetaUrlPdfSource:` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `class BetaFileDocumentSource:` - - - `String fileId` - - - `JsonValue; type "file"constant` - - - `FILE("file")` - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - - `Optional enabled` - - - `Optional context` - - - `Optional title` - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlockParam:` - - - `BetaCodeExecutionToolResultBlockParamContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultErrorParam:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlockParam:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaBashCodeExecutionToolResultBlockParam:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlockParam:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaTextEditorCodeExecutionToolResultBlockParam:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `Optional errorMessage` - - - `class BetaTextEditorCodeExecutionViewResultBlockParam:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `class BetaTextEditorCodeExecutionCreateResultBlockParam:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaToolSearchToolResultBlockParam:` - - - `Content content` - - - `class BetaToolSearchToolResultErrorParam:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlockParam:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaMcpToolUseBlockParam:` - - - `String id` - - - `Input input` - - - `String name` - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaRequestMcpToolResultBlockParam:` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional content` - - - `String` - - - `List` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `Optional isError` - - - `class BetaContainerUploadBlockParam:` - - A content block that represents a file to be uploaded to the container - Files uploaded via this block will be available in the container's input directory. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `class BetaCompactionBlockParam:` - - A compaction block containing summary of previous context. - - Users should round-trip these blocks from responses to subsequent requests - to maintain context across compaction boundaries. - - When content is None, the block represents a failed compaction. The server - treats these as no-ops. Empty string content is not allowed. - - - `Optional content` - - Summary of previously compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Role role` - - - `USER("user")` - - - `ASSISTANT("assistant")` - - - `Model model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - - Most intelligent model for building agents and coding - - - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` - - Best combination of speed and intelligence - - - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_OPUS_4_5("claude-opus-4-5")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` - - High-performance model for agents and coding - - - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` - - High-performance model for agents and coding - - - `CLAUDE_OPUS_4_1("claude-opus-4-1")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_0("claude-opus-4-0")` - - Powerful model for complex tasks - - - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")` - - Powerful model for complex tasks - - - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")` - - High-performance model with extended thinking - - - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")` - - High-performance model with extended thinking - - - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")` - - Fast and cost-effective model - - - `Optional cacheControl` - - Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional container` - - Container identifier for reuse across requests. - - - `class BetaContainerParams:` - - Container parameters with skills to be loaded. - - - `Optional id` - - Container id - - - `Optional> skills` - - List of skills to load in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `Optional version` - - Skill version or 'latest' for most recent version - - - `String` - - - `Optional contextManagement` - - Context management configuration. - - This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. - - - `Optional> edits` - - List of context management edits to apply - - - `class BetaClearToolUses20250919Edit:` - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `Optional clearAtLeast` - - Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed. - - - `JsonValue; type "input_tokens"constant` - - - `INPUT_TOKENS("input_tokens")` - - - `long value` - - - `Optional clearToolInputs` - - Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) - - - `boolean` - - - `List` - - - `Optional> excludeTools` - - Tool names whose uses are preserved from clearing - - - `Optional keep` - - Number of tool uses to retain in the conversation - - - `JsonValue; type "tool_uses"constant` - - - `TOOL_USES("tool_uses")` - - - `long value` - - - `Optional trigger` - - Condition that triggers the context management strategy - - - `class BetaInputTokensTrigger:` - - - `JsonValue; type "input_tokens"constant` - - - `INPUT_TOKENS("input_tokens")` - - - `long value` - - - `class BetaToolUsesTrigger:` - - - `JsonValue; type "tool_uses"constant` - - - `TOOL_USES("tool_uses")` - - - `long value` - - - `class BetaClearThinking20251015Edit:` - - - `JsonValue; type "clear_thinking_20251015"constant` - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Optional keep` - - Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. - - - `class BetaThinkingTurns:` - - - `JsonValue; type "thinking_turns"constant` - - - `THINKING_TURNS("thinking_turns")` - - - `long value` - - - `class BetaAllThinkingTurns:` - - - `JsonValue; type "all"constant` - - - `ALL("all")` - - - `JsonValue;` - - - `ALL("all")` - - - `class BetaCompact20260112Edit:` - - Automatically compact older context when reaching the configured trigger threshold. - - - `JsonValue; type "compact_20260112"constant` - - - `COMPACT_20260112("compact_20260112")` - - - `Optional instructions` - - Additional instructions for summarization. - - - `Optional pauseAfterCompaction` - - Whether to pause after compaction and return the compaction block to the user. - - - `Optional trigger` - - When to trigger compaction. Defaults to 150000 input tokens. - - - `JsonValue; type "input_tokens"constant` - - - `INPUT_TOKENS("input_tokens")` - - - `long value` - - - `Optional inferenceGeo` - - Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. - - - `Optional> mcpServers` - - MCP servers to be utilized in this request - - - `String name` - - - `JsonValue; type "url"constant` - - - `URL("url")` - - - `String url` - - - `Optional authorizationToken` - - - `Optional toolConfiguration` - - - `Optional> allowedTools` - - - `Optional enabled` - - - `Optional metadata` - - An object describing metadata about the request. - - - `Optional userId` - - An external identifier for the user who is associated with the request. - - This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. - - - `Optional outputConfig` - - Configuration options for the model's output, such as the output format. - - - `Optional effort` - - All possible effort levels. - - - `LOW("low")` - - - `MEDIUM("medium")` - - - `HIGH("high")` - - - `MAX("max")` - - - `Optional format` - - A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - - - `Schema schema` - - The JSON schema of the format - - - `JsonValue; type "json_schema"constant` - - - `JSON_SCHEMA("json_schema")` - - - `Optional outputFormat` - - Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - - A schema to specify Claude's output format in responses. This parameter will be removed in a future release. - - - `Schema schema` - - The JSON schema of the format - - - `JsonValue; type "json_schema"constant` - - - `JSON_SCHEMA("json_schema")` - - - `Optional serviceTier` - - Determines whether to use priority capacity (if available) or standard capacity for this request. - - Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. - - - `AUTO("auto")` - - - `STANDARD_ONLY("standard_only")` - - - `Optional speed` - - The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. - - - `STANDARD("standard")` - - - `FAST("fast")` - - - `Optional> stopSequences` - - Custom text sequences that will cause the model to stop generating. - - Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. - - If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. - - - `Optional stream` - - Whether to incrementally stream the response using server-sent events. - - See [streaming](https://docs.claude.com/en/api/messages-streaming) for details. - - - `Optional system` - - System prompt. - - A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). - - - `String` - - - `List` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional> citations` - - - `class BetaCitationCharLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocationParam:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationWebSearchResultLocationParam:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocationParam:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `Optional temperature` - - Amount of randomness injected into the response. - - Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. - - Note that even with `temperature` of `0.0`, the results will not be fully deterministic. - - - `Optional thinking` - - Configuration for enabling Claude's extended thinking. - - When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `class BetaThinkingConfigEnabled:` - - - `long budgetTokens` - - Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. - - Must be ≥1024 and less than `max_tokens`. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `JsonValue; type "enabled"constant` - - - `ENABLED("enabled")` - - - `Optional display` - - Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - - - `SUMMARIZED("summarized")` - - - `OMITTED("omitted")` - - - `class BetaThinkingConfigDisabled:` - - - `JsonValue; type "disabled"constant` - - - `DISABLED("disabled")` - - - `class BetaThinkingConfigAdaptive:` - - - `JsonValue; type "adaptive"constant` - - - `ADAPTIVE("adaptive")` - - - `Optional display` - - Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - - - `SUMMARIZED("summarized")` - - - `OMITTED("omitted")` - - - `Optional toolChoice` - - How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. - - - `class BetaToolChoiceAuto:` - - The model will automatically decide whether to use tools. - - - `JsonValue; type "auto"constant` - - - `AUTO("auto")` - - - `Optional disableParallelToolUse` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output at most one tool use. - - - `class BetaToolChoiceAny:` - - The model will use any available tools. - - - `JsonValue; type "any"constant` - - - `ANY("any")` - - - `Optional disableParallelToolUse` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - - `class BetaToolChoiceTool:` - - The model will use the specified tool with `tool_choice.name`. - - - `String name` - - The name of the tool to use. - - - `JsonValue; type "tool"constant` - - - `TOOL("tool")` - - - `Optional disableParallelToolUse` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - - `class BetaToolChoiceNone:` - - The model will not be allowed to use tools. - - - `JsonValue; type "none"constant` - - - `NONE("none")` - - - `Optional> tools` - - Definitions of tools that the model may use. - - If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. - - There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). - - Each tool definition includes: - - * `name`: Name of the tool. - * `description`: Optional, but strongly-recommended description of the tool. - * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. - - For example, if you defined `tools` as: - - ```json - [ - { - "name": "get_stock_price", - "description": "Get the current stock price for a given ticker symbol.", - "input_schema": { - "type": "object", - "properties": { - "ticker": { - "type": "string", - "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." - } - }, - "required": ["ticker"] - } - } - ] - ``` - - And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: - - ```json - [ - { - "type": "tool_use", - "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "name": "get_stock_price", - "input": { "ticker": "^GSPC" } - } - ] - ``` - - You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: - - ```json - [ - { - "type": "tool_result", - "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "content": "259.75 USD" - } - ] - ``` - - Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. - - See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. - - - `class BetaTool:` - - - `InputSchema inputSchema` - - [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. - - This defines the shape of the `input` that your tool accepts and that the model will produce. - - - `JsonValue; type "object"constant` - - - `OBJECT("object")` - - - `Optional properties` - - - `Optional> required` - - - `String name` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional description` - - Description of what this tool does. - - Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - - - `Optional eagerInputStreaming` - - Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional type` - - - `CUSTOM("custom")` - - - `class BetaToolBash20241022:` - - - `JsonValue; name "bash"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `BASH("bash")` - - - `JsonValue; type "bash_20241022"constant` - - - `BASH_20241022("bash_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolBash20250124:` - - - `JsonValue; name "bash"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `BASH("bash")` - - - `JsonValue; type "bash_20250124"constant` - - - `BASH_20250124("bash_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaCodeExecutionTool20250522:` - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20250522"constant` - - - `CODE_EXECUTION_20250522("code_execution_20250522")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaCodeExecutionTool20250825:` - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaCodeExecutionTool20260120:` - - Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - - - `JsonValue; name "code_execution"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `CODE_EXECUTION("code_execution")` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolComputerUse20241022:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20241022"constant` - - - `COMPUTER_20241022("computer_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaMemoryTool20250818:` - - - `JsonValue; name "memory"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `MEMORY("memory")` - - - `JsonValue; type "memory_20250818"constant` - - - `MEMORY_20250818("memory_20250818")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolComputerUse20250124:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20250124"constant` - - - `COMPUTER_20250124("computer_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20241022:` - - - `JsonValue; name "str_replace_editor"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_EDITOR("str_replace_editor")` - - - `JsonValue; type "text_editor_20241022"constant` - - - `TEXT_EDITOR_20241022("text_editor_20241022")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolComputerUse20251124:` - - - `long displayHeightPx` - - The height of the display in pixels. - - - `long displayWidthPx` - - The width of the display in pixels. - - - `JsonValue; name "computer"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `COMPUTER("computer")` - - - `JsonValue; type "computer_20251124"constant` - - - `COMPUTER_20251124("computer_20251124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional displayNumber` - - The X11 display number (e.g. 0, 1) for the display. - - - `Optional enableZoom` - - Whether to enable an action to take a zoomed-in screenshot of the screen. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20250124:` - - - `JsonValue; name "str_replace_editor"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_EDITOR("str_replace_editor")` - - - `JsonValue; type "text_editor_20250124"constant` - - - `TEXT_EDITOR_20250124("text_editor_20250124")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20250429:` - - - `JsonValue; name "str_replace_based_edit_tool"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")` - - - `JsonValue; type "text_editor_20250429"constant` - - - `TEXT_EDITOR_20250429("text_editor_20250429")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolTextEditor20250728:` - - - `JsonValue; name "str_replace_based_edit_tool"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")` - - - `JsonValue; type "text_editor_20250728"constant` - - - `TEXT_EDITOR_20250728("text_editor_20250728")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional> inputExamples` - - - `Optional maxCharacters` - - Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaWebSearchTool20250305:` - - - `JsonValue; name "web_search"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_SEARCH("web_search")` - - - `JsonValue; type "web_search_20250305"constant` - - - `WEB_SEARCH_20250305("web_search_20250305")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `Optional> blockedDomains` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional userLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `JsonValue; type "approximate"constant` - - - `APPROXIMATE("approximate")` - - - `Optional city` - - The city of the user. - - - `Optional country` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `Optional region` - - The region of the user. - - - `Optional timezone` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `class BetaWebFetchTool20250910:` - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20250910"constant` - - - `WEB_FETCH_20250910("web_fetch_20250910")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaWebSearchTool20260209:` - - - `JsonValue; name "web_search"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_SEARCH("web_search")` - - - `JsonValue; type "web_search_20260209"constant` - - - `WEB_SEARCH_20260209("web_search_20260209")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `Optional> blockedDomains` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional userLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `JsonValue; type "approximate"constant` - - - `APPROXIMATE("approximate")` - - - `Optional city` - - The city of the user. - - - `Optional country` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `Optional region` - - The region of the user. - - - `Optional timezone` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `class BetaWebFetchTool20260209:` - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20260209"constant` - - - `WEB_FETCH_20260209("web_fetch_20260209")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaWebFetchTool20260309:` - - Web fetch tool with use_cache parameter for bypassing cached content. - - - `JsonValue; name "web_fetch"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `WEB_FETCH("web_fetch")` - - - `JsonValue; type "web_fetch_20260309"constant` - - - `WEB_FETCH_20260309("web_fetch_20260309")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional> allowedDomains` - - List of domains to allow fetching from - - - `Optional> blockedDomains` - - List of domains to block fetching from - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional citations` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `Optional enabled` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional maxContentTokens` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `Optional maxUses` - - Maximum number of times the tool can be used in the API request. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `Optional useCache` - - Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - - - `class BetaToolSearchToolBm25_20251119:` - - - `JsonValue; name "tool_search_tool_bm25"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `Type type` - - - `TOOL_SEARCH_TOOL_BM25_20251119("tool_search_tool_bm25_20251119")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaToolSearchToolRegex20251119:` - - - `JsonValue; name "tool_search_tool_regex"constant` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `Type type` - - - `TOOL_SEARCH_TOOL_REGEX_20251119("tool_search_tool_regex_20251119")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `Optional> allowedCallers` - - - `DIRECT("direct")` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional deferLoading` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `Optional strict` - - When true, guarantees schema validation on tool names and inputs - - - `class BetaMcpToolset:` - - Configuration for a group of tools from an MCP server. - - Allows configuring enabled status and defer_loading for all tools - from an MCP server, with optional per-tool overrides. - - - `String mcpServerName` - - Name of the MCP server to configure tools for - - - `JsonValue; type "mcp_toolset"constant` - - - `MCP_TOOLSET("mcp_toolset")` - - - `Optional cacheControl` - - Create a cache control breakpoint at this content block. - - - `JsonValue; type "ephemeral"constant` - - - `EPHEMERAL("ephemeral")` - - - `Optional ttl` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `TTL_5M("5m")` - - - `TTL_1H("1h")` - - - `Optional configs` - - Configuration overrides for specific tools, keyed by tool name - - - `Optional deferLoading` - - - `Optional enabled` - - - `Optional defaultConfig` - - Default configuration applied to all tools from this server - - - `Optional deferLoading` - - - `Optional enabled` - - - `Optional topK` - - Only sample from the top K options for each subsequent token. - - Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). - - Recommended for advanced use cases only. You usually only need to use `temperature`. - - - `Optional topP` - - Use nucleus sampling. - - In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. - - Recommended for advanced use cases only. You usually only need to use `temperature`. - - - `Optional userProfileId` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - -### Returns - -- `class BetaMessageBatch:` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional archivedAt` - - RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - - - `Optional cancelInitiatedAt` - - RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - - - `LocalDateTime createdAt` - - RFC 3339 datetime string representing the time at which the Message Batch was created. - - - `Optional endedAt` - - RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. - - Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - - - `LocalDateTime expiresAt` - - RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - - - `ProcessingStatus processingStatus` - - Processing status of the Message Batch. - - - `IN_PROGRESS("in_progress")` - - - `CANCELING("canceling")` - - - `ENDED("ended")` - - - `BetaMessageBatchRequestCounts requestCounts` - - Tallies requests within the Message Batch, categorized by their status. - - Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - - - `long canceled` - - Number of requests in the Message Batch that have been canceled. - - This is zero until processing of the entire Message Batch has ended. - - - `long errored` - - Number of requests in the Message Batch that encountered an error. - - This is zero until processing of the entire Message Batch has ended. - - - `long expired` - - Number of requests in the Message Batch that have expired. - - This is zero until processing of the entire Message Batch has ended. - - - `long processing` - - Number of requests in the Message Batch that are processing. - - - `long succeeded` - - Number of requests in the Message Batch that have completed successfully. - - This is zero until processing of the entire Message Batch has ended. - - - `Optional resultsUrl` - - URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. - - Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - - - `JsonValue; type "message_batch"constant` - - Object type. - - For Message Batches, this is always `"message_batch"`. - - - `MESSAGE_BATCH("message_batch")` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.messages.batches.BatchCreateParams; -import com.anthropic.models.beta.messages.batches.BetaMessageBatch; -import com.anthropic.models.messages.Model; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - BatchCreateParams params = BatchCreateParams.builder() - .addRequest(BatchCreateParams.Request.builder() - .customId("my-custom-id-1") - .params(BatchCreateParams.Request.Params.builder() - .maxTokens(1024L) - .addUserMessage("Hello, world") - .model(Model.CLAUDE_OPUS_4_6) - .build()) - .build()) - .build(); - BetaMessageBatch betaMessageBatch = client.beta().messages().batches().create(params); - } -} -``` - -## Retrieve - -`BetaMessageBatch beta().messages().batches().retrieve(BatchRetrieveParamsparams = BatchRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/messages/batches/{message_batch_id}` - -This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response. - -Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) - -### Parameters - -- `BatchRetrieveParams params` - - - `Optional messageBatchId` - - ID of the Message Batch. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class BetaMessageBatch:` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional archivedAt` - - RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - - - `Optional cancelInitiatedAt` - - RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - - - `LocalDateTime createdAt` - - RFC 3339 datetime string representing the time at which the Message Batch was created. - - - `Optional endedAt` - - RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. - - Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - - - `LocalDateTime expiresAt` - - RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - - - `ProcessingStatus processingStatus` - - Processing status of the Message Batch. - - - `IN_PROGRESS("in_progress")` - - - `CANCELING("canceling")` - - - `ENDED("ended")` - - - `BetaMessageBatchRequestCounts requestCounts` - - Tallies requests within the Message Batch, categorized by their status. - - Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - - - `long canceled` - - Number of requests in the Message Batch that have been canceled. - - This is zero until processing of the entire Message Batch has ended. - - - `long errored` - - Number of requests in the Message Batch that encountered an error. - - This is zero until processing of the entire Message Batch has ended. - - - `long expired` - - Number of requests in the Message Batch that have expired. - - This is zero until processing of the entire Message Batch has ended. - - - `long processing` - - Number of requests in the Message Batch that are processing. - - - `long succeeded` - - Number of requests in the Message Batch that have completed successfully. - - This is zero until processing of the entire Message Batch has ended. - - - `Optional resultsUrl` - - URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. - - Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - - - `JsonValue; type "message_batch"constant` - - Object type. - - For Message Batches, this is always `"message_batch"`. - - - `MESSAGE_BATCH("message_batch")` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.messages.batches.BatchRetrieveParams; -import com.anthropic.models.beta.messages.batches.BetaMessageBatch; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - BetaMessageBatch betaMessageBatch = client.beta().messages().batches().retrieve("message_batch_id"); - } -} -``` - -## List - -`BatchListPage beta().messages().batches().list(BatchListParamsparams = BatchListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/messages/batches` - -List all Message Batches within a Workspace. Most recently created batches are returned first. - -Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) - -### Parameters - -- `BatchListParams params` - - - `Optional afterId` - - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - - - `Optional beforeId` - - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - - - `Optional limit` - - Number of items to return per page. - - Defaults to `20`. Ranges from `1` to `1000`. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class BetaMessageBatch:` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional archivedAt` - - RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - - - `Optional cancelInitiatedAt` - - RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - - - `LocalDateTime createdAt` - - RFC 3339 datetime string representing the time at which the Message Batch was created. - - - `Optional endedAt` - - RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. - - Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - - - `LocalDateTime expiresAt` - - RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - - - `ProcessingStatus processingStatus` - - Processing status of the Message Batch. - - - `IN_PROGRESS("in_progress")` - - - `CANCELING("canceling")` - - - `ENDED("ended")` - - - `BetaMessageBatchRequestCounts requestCounts` - - Tallies requests within the Message Batch, categorized by their status. - - Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - - - `long canceled` - - Number of requests in the Message Batch that have been canceled. - - This is zero until processing of the entire Message Batch has ended. - - - `long errored` - - Number of requests in the Message Batch that encountered an error. - - This is zero until processing of the entire Message Batch has ended. - - - `long expired` - - Number of requests in the Message Batch that have expired. - - This is zero until processing of the entire Message Batch has ended. - - - `long processing` - - Number of requests in the Message Batch that are processing. - - - `long succeeded` - - Number of requests in the Message Batch that have completed successfully. - - This is zero until processing of the entire Message Batch has ended. - - - `Optional resultsUrl` - - URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. - - Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - - - `JsonValue; type "message_batch"constant` - - Object type. - - For Message Batches, this is always `"message_batch"`. - - - `MESSAGE_BATCH("message_batch")` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.messages.batches.BatchListPage; -import com.anthropic.models.beta.messages.batches.BatchListParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - BatchListPage page = client.beta().messages().batches().list(); - } -} -``` - -## Cancel - -`BetaMessageBatch beta().messages().batches().cancel(BatchCancelParamsparams = BatchCancelParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**post** `/v1/messages/batches/{message_batch_id}/cancel` - -Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. - -The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. - -Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) - -### Parameters - -- `BatchCancelParams params` - - - `Optional messageBatchId` - - ID of the Message Batch. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class BetaMessageBatch:` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional archivedAt` - - RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - - - `Optional cancelInitiatedAt` - - RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - - - `LocalDateTime createdAt` - - RFC 3339 datetime string representing the time at which the Message Batch was created. - - - `Optional endedAt` - - RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. - - Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - - - `LocalDateTime expiresAt` - - RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - - - `ProcessingStatus processingStatus` - - Processing status of the Message Batch. - - - `IN_PROGRESS("in_progress")` - - - `CANCELING("canceling")` - - - `ENDED("ended")` - - - `BetaMessageBatchRequestCounts requestCounts` - - Tallies requests within the Message Batch, categorized by their status. - - Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - - - `long canceled` - - Number of requests in the Message Batch that have been canceled. - - This is zero until processing of the entire Message Batch has ended. - - - `long errored` - - Number of requests in the Message Batch that encountered an error. - - This is zero until processing of the entire Message Batch has ended. - - - `long expired` - - Number of requests in the Message Batch that have expired. - - This is zero until processing of the entire Message Batch has ended. - - - `long processing` - - Number of requests in the Message Batch that are processing. - - - `long succeeded` - - Number of requests in the Message Batch that have completed successfully. - - This is zero until processing of the entire Message Batch has ended. - - - `Optional resultsUrl` - - URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. - - Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - - - `JsonValue; type "message_batch"constant` - - Object type. - - For Message Batches, this is always `"message_batch"`. - - - `MESSAGE_BATCH("message_batch")` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.messages.batches.BatchCancelParams; -import com.anthropic.models.beta.messages.batches.BetaMessageBatch; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - BetaMessageBatch betaMessageBatch = client.beta().messages().batches().cancel("message_batch_id"); - } -} -``` - -## Delete - -`BetaDeletedMessageBatch beta().messages().batches().delete(BatchDeleteParamsparams = BatchDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**delete** `/v1/messages/batches/{message_batch_id}` - -Delete a Message Batch. - -Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it. - -Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) - -### Parameters - -- `BatchDeleteParams params` - - - `Optional messageBatchId` - - ID of the Message Batch. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class BetaDeletedMessageBatch:` - - - `String id` - - ID of the Message Batch. - - - `JsonValue; type "message_batch_deleted"constant` - - Deleted object type. - - For Message Batches, this is always `"message_batch_deleted"`. - - - `MESSAGE_BATCH_DELETED("message_batch_deleted")` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.messages.batches.BatchDeleteParams; -import com.anthropic.models.beta.messages.batches.BetaDeletedMessageBatch; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - BetaDeletedMessageBatch betaDeletedMessageBatch = client.beta().messages().batches().delete("message_batch_id"); - } -} -``` - -## Results - -`BetaMessageBatchIndividualResponse beta().messages().batches().resultsStreaming(BatchResultsParamsparams = BatchResultsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/messages/batches/{message_batch_id}/results` - -Streams the results of a Message Batch as a `.jsonl` file. - -Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - -Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) - -### Parameters - -- `BatchResultsParams params` - - - `Optional messageBatchId` - - ID of the Message Batch. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class BetaMessageBatchIndividualResponse:` - - This is a single line in the response `.jsonl` file and does not represent the response as a whole. - - - `String customId` - - Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. - - Must be unique for each request within the Message Batch. - - - `BetaMessageBatchResult result` - - Processing result for this request. - - Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. - - - `class BetaMessageBatchSucceededResult:` - - - `BetaMessage message` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional container` - - Information about the container used in the request (for the code execution tool) - - - `String id` - - Identifier for the container used in this request - - - `LocalDateTime expiresAt` - - The time at which the container will expire. - - - `Optional> skills` - - Skills loaded in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `String version` - - Skill version or 'latest' for most recent version - - - `List content` - - Content generated by the model. - - This is an array of content blocks, each of which has a `type` that determines its shape. - - Example: - - ```json - [{"type": "text", "text": "Hi, I'm Claude."}] - ``` - - If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. - - For example, if the input `messages` were: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("} - ] - ``` - - Then the response `content` might be: - - ```json - [{"type": "text", "text": "B)"}] - ``` - - - `class BetaTextBlock:` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaThinkingBlock:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlock:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaServerToolUseBlock:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlock:` - - - `BetaWebSearchToolResultBlockContent content` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlock:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlock:` - - - `BetaCodeExecutionToolResultBlockContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `class BetaBashCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `class BetaTextEditorCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `class BetaToolSearchToolResultBlock:` - - - `Content content` - - - `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `class BetaMcpToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - The name of the MCP tool - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `class BetaMcpToolResultBlock:` - - - `Content content` - - - `String` - - - `List` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `boolean isError` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `class BetaContainerUploadBlock:` - - Response model for a file uploaded to the container. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `class BetaCompactionBlock:` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `Optional content` - - Summary of compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional contextManagement` - - Context management response. - - Information about context management strategies applied during the request. - - - `List appliedEdits` - - List of context management edits that were applied. - - - `class BetaClearToolUses20250919EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedToolUses` - - Number of tool uses that were cleared. - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - The type of context management edit applied. - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `class BetaClearThinking20251015EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedThinkingTurns` - - Number of thinking turns that were cleared. - - - `JsonValue; type "clear_thinking_20251015"constant` - - The type of context management edit applied. - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Model model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - - Most intelligent model for building agents and coding - - - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` - - Best combination of speed and intelligence - - - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_OPUS_4_5("claude-opus-4-5")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` - - High-performance model for agents and coding - - - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` - - High-performance model for agents and coding - - - `CLAUDE_OPUS_4_1("claude-opus-4-1")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_0("claude-opus-4-0")` - - Powerful model for complex tasks - - - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")` - - Powerful model for complex tasks - - - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")` - - High-performance model with extended thinking - - - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")` - - High-performance model with extended thinking - - - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")` - - Fast and cost-effective model - - - `JsonValue; role "assistant"constant` - - Conversational role of the generated message. - - This will always be `"assistant"`. - - - `ASSISTANT("assistant")` - - - `Optional stopDetails` - - Structured information about a refusal. - - - `Optional category` - - The policy category that triggered the refusal. - - `null` when the refusal doesn't map to a named category. - - - `CYBER("cyber")` - - - `BIO("bio")` - - - `Optional explanation` - - Human-readable explanation of the refusal. - - This text is not guaranteed to be stable. `null` when no explanation is available for the category. - - - `JsonValue; type "refusal"constant` - - - `REFUSAL("refusal")` - - - `Optional stopReason` - - The reason that we stopped. - - This may be one the following values: - - * `"end_turn"`: the model reached a natural stopping point - * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - * `"tool_use"`: the model invoked one or more tools - * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - * `"refusal"`: when streaming classifiers intervene to handle potential policy violations - - In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - - - `END_TURN("end_turn")` - - - `MAX_TOKENS("max_tokens")` - - - `STOP_SEQUENCE("stop_sequence")` - - - `TOOL_USE("tool_use")` - - - `PAUSE_TURN("pause_turn")` - - - `COMPACTION("compaction")` - - - `REFUSAL("refusal")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")` - - - `Optional stopSequence` - - Which custom stop sequence was generated, if any. - - This value will be a non-null string if one of your custom stop sequences was generated. - - - `JsonValue; type "message"constant` - - Object type. - - For Messages, this is always `"message"`. - - - `MESSAGE("message")` - - - `BetaUsage usage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `Optional cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `Optional cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `Optional inferenceGeo` - - The geographic region where inference was performed for this request. - - - `long inputTokens` - - The number of input tokens which were used. - - - `Optional> iterations` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - - - `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - - - `long outputTokens` - - The number of output tokens which were used. - - - `Optional serverToolUse` - - The number of server tool requests. - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - - - `Optional serviceTier` - - If the request used the priority, standard, or batch tier. - - - `STANDARD("standard")` - - - `PRIORITY("priority")` - - - `BATCH("batch")` - - - `Optional speed` - - The inference speed mode used for this request. - - - `STANDARD("standard")` - - - `FAST("fast")` - - - `JsonValue; type "succeeded"constant` - - - `SUCCEEDED("succeeded")` - - - `class BetaMessageBatchErroredResult:` - - - `BetaErrorResponse error` - - - `BetaError error` - - - `class BetaInvalidRequestError:` - - - `String message` - - - `JsonValue; type "invalid_request_error"constant` - - - `INVALID_REQUEST_ERROR("invalid_request_error")` - - - `class BetaAuthenticationError:` - - - `String message` - - - `JsonValue; type "authentication_error"constant` - - - `AUTHENTICATION_ERROR("authentication_error")` - - - `class BetaBillingError:` - - - `String message` - - - `JsonValue; type "billing_error"constant` - - - `BILLING_ERROR("billing_error")` - - - `class BetaPermissionError:` - - - `String message` - - - `JsonValue; type "permission_error"constant` - - - `PERMISSION_ERROR("permission_error")` - - - `class BetaNotFoundError:` - - - `String message` - - - `JsonValue; type "not_found_error"constant` - - - `NOT_FOUND_ERROR("not_found_error")` - - - `class BetaRateLimitError:` - - - `String message` - - - `JsonValue; type "rate_limit_error"constant` - - - `RATE_LIMIT_ERROR("rate_limit_error")` - - - `class BetaGatewayTimeoutError:` - - - `String message` - - - `JsonValue; type "timeout_error"constant` - - - `TIMEOUT_ERROR("timeout_error")` - - - `class BetaApiError:` - - - `String message` - - - `JsonValue; type "api_error"constant` - - - `API_ERROR("api_error")` - - - `class BetaOverloadedError:` - - - `String message` - - - `JsonValue; type "overloaded_error"constant` - - - `OVERLOADED_ERROR("overloaded_error")` - - - `Optional requestId` - - - `JsonValue; type "error"constant` - - - `ERROR("error")` - - - `JsonValue; type "errored"constant` - - - `ERRORED("errored")` - - - `class BetaMessageBatchCanceledResult:` - - - `JsonValue; type "canceled"constant` - - - `CANCELED("canceled")` - - - `class BetaMessageBatchExpiredResult:` - - - `JsonValue; type "expired"constant` - - - `EXPIRED("expired")` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.core.http.StreamResponse; -import com.anthropic.models.beta.messages.batches.BatchResultsParams; -import com.anthropic.models.beta.messages.batches.BetaMessageBatchIndividualResponse; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - StreamResponse betaMessageBatchIndividualResponse = client.beta().messages().batches().resultsStreaming("message_batch_id"); - } -} -``` - -## Domain Types - -### Beta Deleted Message Batch - -- `class BetaDeletedMessageBatch:` - - - `String id` - - ID of the Message Batch. - - - `JsonValue; type "message_batch_deleted"constant` - - Deleted object type. - - For Message Batches, this is always `"message_batch_deleted"`. - - - `MESSAGE_BATCH_DELETED("message_batch_deleted")` - -### Beta Message Batch - -- `class BetaMessageBatch:` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional archivedAt` - - RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - - - `Optional cancelInitiatedAt` - - RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - - - `LocalDateTime createdAt` - - RFC 3339 datetime string representing the time at which the Message Batch was created. - - - `Optional endedAt` - - RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. - - Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - - - `LocalDateTime expiresAt` - - RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - - - `ProcessingStatus processingStatus` - - Processing status of the Message Batch. - - - `IN_PROGRESS("in_progress")` - - - `CANCELING("canceling")` - - - `ENDED("ended")` - - - `BetaMessageBatchRequestCounts requestCounts` - - Tallies requests within the Message Batch, categorized by their status. - - Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - - - `long canceled` - - Number of requests in the Message Batch that have been canceled. - - This is zero until processing of the entire Message Batch has ended. - - - `long errored` - - Number of requests in the Message Batch that encountered an error. - - This is zero until processing of the entire Message Batch has ended. - - - `long expired` - - Number of requests in the Message Batch that have expired. - - This is zero until processing of the entire Message Batch has ended. - - - `long processing` - - Number of requests in the Message Batch that are processing. - - - `long succeeded` - - Number of requests in the Message Batch that have completed successfully. - - This is zero until processing of the entire Message Batch has ended. - - - `Optional resultsUrl` - - URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. - - Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - - - `JsonValue; type "message_batch"constant` - - Object type. - - For Message Batches, this is always `"message_batch"`. - - - `MESSAGE_BATCH("message_batch")` - -### Beta Message Batch Canceled Result - -- `class BetaMessageBatchCanceledResult:` - - - `JsonValue; type "canceled"constant` - - - `CANCELED("canceled")` - -### Beta Message Batch Errored Result - -- `class BetaMessageBatchErroredResult:` - - - `BetaErrorResponse error` - - - `BetaError error` - - - `class BetaInvalidRequestError:` - - - `String message` - - - `JsonValue; type "invalid_request_error"constant` - - - `INVALID_REQUEST_ERROR("invalid_request_error")` - - - `class BetaAuthenticationError:` - - - `String message` - - - `JsonValue; type "authentication_error"constant` - - - `AUTHENTICATION_ERROR("authentication_error")` - - - `class BetaBillingError:` - - - `String message` - - - `JsonValue; type "billing_error"constant` - - - `BILLING_ERROR("billing_error")` - - - `class BetaPermissionError:` - - - `String message` - - - `JsonValue; type "permission_error"constant` - - - `PERMISSION_ERROR("permission_error")` - - - `class BetaNotFoundError:` - - - `String message` - - - `JsonValue; type "not_found_error"constant` - - - `NOT_FOUND_ERROR("not_found_error")` - - - `class BetaRateLimitError:` - - - `String message` - - - `JsonValue; type "rate_limit_error"constant` - - - `RATE_LIMIT_ERROR("rate_limit_error")` - - - `class BetaGatewayTimeoutError:` - - - `String message` - - - `JsonValue; type "timeout_error"constant` - - - `TIMEOUT_ERROR("timeout_error")` - - - `class BetaApiError:` - - - `String message` - - - `JsonValue; type "api_error"constant` - - - `API_ERROR("api_error")` - - - `class BetaOverloadedError:` - - - `String message` - - - `JsonValue; type "overloaded_error"constant` - - - `OVERLOADED_ERROR("overloaded_error")` - - - `Optional requestId` - - - `JsonValue; type "error"constant` - - - `ERROR("error")` - - - `JsonValue; type "errored"constant` - - - `ERRORED("errored")` - -### Beta Message Batch Expired Result - -- `class BetaMessageBatchExpiredResult:` - - - `JsonValue; type "expired"constant` - - - `EXPIRED("expired")` - -### Beta Message Batch Individual Response - -- `class BetaMessageBatchIndividualResponse:` - - This is a single line in the response `.jsonl` file and does not represent the response as a whole. - - - `String customId` - - Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. - - Must be unique for each request within the Message Batch. - - - `BetaMessageBatchResult result` - - Processing result for this request. - - Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. - - - `class BetaMessageBatchSucceededResult:` - - - `BetaMessage message` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional container` - - Information about the container used in the request (for the code execution tool) - - - `String id` - - Identifier for the container used in this request - - - `LocalDateTime expiresAt` - - The time at which the container will expire. - - - `Optional> skills` - - Skills loaded in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `String version` - - Skill version or 'latest' for most recent version - - - `List content` - - Content generated by the model. - - This is an array of content blocks, each of which has a `type` that determines its shape. - - Example: - - ```json - [{"type": "text", "text": "Hi, I'm Claude."}] - ``` - - If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. - - For example, if the input `messages` were: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("} - ] - ``` - - Then the response `content` might be: - - ```json - [{"type": "text", "text": "B)"}] - ``` - - - `class BetaTextBlock:` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaThinkingBlock:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlock:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaServerToolUseBlock:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlock:` - - - `BetaWebSearchToolResultBlockContent content` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlock:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlock:` - - - `BetaCodeExecutionToolResultBlockContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `class BetaBashCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `class BetaTextEditorCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `class BetaToolSearchToolResultBlock:` - - - `Content content` - - - `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `class BetaMcpToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - The name of the MCP tool - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `class BetaMcpToolResultBlock:` - - - `Content content` - - - `String` - - - `List` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `boolean isError` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `class BetaContainerUploadBlock:` - - Response model for a file uploaded to the container. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `class BetaCompactionBlock:` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `Optional content` - - Summary of compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional contextManagement` - - Context management response. - - Information about context management strategies applied during the request. - - - `List appliedEdits` - - List of context management edits that were applied. - - - `class BetaClearToolUses20250919EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedToolUses` - - Number of tool uses that were cleared. - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - The type of context management edit applied. - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `class BetaClearThinking20251015EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedThinkingTurns` - - Number of thinking turns that were cleared. - - - `JsonValue; type "clear_thinking_20251015"constant` - - The type of context management edit applied. - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Model model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - - Most intelligent model for building agents and coding - - - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` - - Best combination of speed and intelligence - - - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_OPUS_4_5("claude-opus-4-5")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` - - High-performance model for agents and coding - - - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` - - High-performance model for agents and coding - - - `CLAUDE_OPUS_4_1("claude-opus-4-1")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_0("claude-opus-4-0")` - - Powerful model for complex tasks - - - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")` - - Powerful model for complex tasks - - - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")` - - High-performance model with extended thinking - - - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")` - - High-performance model with extended thinking - - - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")` - - Fast and cost-effective model - - - `JsonValue; role "assistant"constant` - - Conversational role of the generated message. - - This will always be `"assistant"`. - - - `ASSISTANT("assistant")` - - - `Optional stopDetails` - - Structured information about a refusal. - - - `Optional category` - - The policy category that triggered the refusal. - - `null` when the refusal doesn't map to a named category. - - - `CYBER("cyber")` - - - `BIO("bio")` - - - `Optional explanation` - - Human-readable explanation of the refusal. - - This text is not guaranteed to be stable. `null` when no explanation is available for the category. - - - `JsonValue; type "refusal"constant` - - - `REFUSAL("refusal")` - - - `Optional stopReason` - - The reason that we stopped. - - This may be one the following values: - - * `"end_turn"`: the model reached a natural stopping point - * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - * `"tool_use"`: the model invoked one or more tools - * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - * `"refusal"`: when streaming classifiers intervene to handle potential policy violations - - In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - - - `END_TURN("end_turn")` - - - `MAX_TOKENS("max_tokens")` - - - `STOP_SEQUENCE("stop_sequence")` - - - `TOOL_USE("tool_use")` - - - `PAUSE_TURN("pause_turn")` - - - `COMPACTION("compaction")` - - - `REFUSAL("refusal")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")` - - - `Optional stopSequence` - - Which custom stop sequence was generated, if any. - - This value will be a non-null string if one of your custom stop sequences was generated. - - - `JsonValue; type "message"constant` - - Object type. - - For Messages, this is always `"message"`. - - - `MESSAGE("message")` - - - `BetaUsage usage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `Optional cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `Optional cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `Optional inferenceGeo` - - The geographic region where inference was performed for this request. - - - `long inputTokens` - - The number of input tokens which were used. - - - `Optional> iterations` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - - - `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - - - `long outputTokens` - - The number of output tokens which were used. - - - `Optional serverToolUse` - - The number of server tool requests. - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - - - `Optional serviceTier` - - If the request used the priority, standard, or batch tier. - - - `STANDARD("standard")` - - - `PRIORITY("priority")` - - - `BATCH("batch")` - - - `Optional speed` - - The inference speed mode used for this request. - - - `STANDARD("standard")` - - - `FAST("fast")` - - - `JsonValue; type "succeeded"constant` - - - `SUCCEEDED("succeeded")` - - - `class BetaMessageBatchErroredResult:` - - - `BetaErrorResponse error` - - - `BetaError error` - - - `class BetaInvalidRequestError:` - - - `String message` - - - `JsonValue; type "invalid_request_error"constant` - - - `INVALID_REQUEST_ERROR("invalid_request_error")` - - - `class BetaAuthenticationError:` - - - `String message` - - - `JsonValue; type "authentication_error"constant` - - - `AUTHENTICATION_ERROR("authentication_error")` - - - `class BetaBillingError:` - - - `String message` - - - `JsonValue; type "billing_error"constant` - - - `BILLING_ERROR("billing_error")` - - - `class BetaPermissionError:` - - - `String message` - - - `JsonValue; type "permission_error"constant` - - - `PERMISSION_ERROR("permission_error")` - - - `class BetaNotFoundError:` - - - `String message` - - - `JsonValue; type "not_found_error"constant` - - - `NOT_FOUND_ERROR("not_found_error")` - - - `class BetaRateLimitError:` - - - `String message` - - - `JsonValue; type "rate_limit_error"constant` - - - `RATE_LIMIT_ERROR("rate_limit_error")` - - - `class BetaGatewayTimeoutError:` - - - `String message` - - - `JsonValue; type "timeout_error"constant` - - - `TIMEOUT_ERROR("timeout_error")` - - - `class BetaApiError:` - - - `String message` - - - `JsonValue; type "api_error"constant` - - - `API_ERROR("api_error")` - - - `class BetaOverloadedError:` - - - `String message` - - - `JsonValue; type "overloaded_error"constant` - - - `OVERLOADED_ERROR("overloaded_error")` - - - `Optional requestId` - - - `JsonValue; type "error"constant` - - - `ERROR("error")` - - - `JsonValue; type "errored"constant` - - - `ERRORED("errored")` - - - `class BetaMessageBatchCanceledResult:` - - - `JsonValue; type "canceled"constant` - - - `CANCELED("canceled")` - - - `class BetaMessageBatchExpiredResult:` - - - `JsonValue; type "expired"constant` - - - `EXPIRED("expired")` - -### Beta Message Batch Request Counts - -- `class BetaMessageBatchRequestCounts:` - - - `long canceled` - - Number of requests in the Message Batch that have been canceled. - - This is zero until processing of the entire Message Batch has ended. - - - `long errored` - - Number of requests in the Message Batch that encountered an error. - - This is zero until processing of the entire Message Batch has ended. - - - `long expired` - - Number of requests in the Message Batch that have expired. - - This is zero until processing of the entire Message Batch has ended. - - - `long processing` - - Number of requests in the Message Batch that are processing. - - - `long succeeded` - - Number of requests in the Message Batch that have completed successfully. - - This is zero until processing of the entire Message Batch has ended. - -### Beta Message Batch Result - -- `class BetaMessageBatchResult: A class that can be one of several variants.union` - - Processing result for this request. - - Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. - - - `class BetaMessageBatchSucceededResult:` - - - `BetaMessage message` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional container` - - Information about the container used in the request (for the code execution tool) - - - `String id` - - Identifier for the container used in this request - - - `LocalDateTime expiresAt` - - The time at which the container will expire. - - - `Optional> skills` - - Skills loaded in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `String version` - - Skill version or 'latest' for most recent version - - - `List content` - - Content generated by the model. - - This is an array of content blocks, each of which has a `type` that determines its shape. - - Example: - - ```json - [{"type": "text", "text": "Hi, I'm Claude."}] - ``` - - If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. - - For example, if the input `messages` were: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("} - ] - ``` - - Then the response `content` might be: - - ```json - [{"type": "text", "text": "B)"}] - ``` - - - `class BetaTextBlock:` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaThinkingBlock:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlock:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaServerToolUseBlock:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlock:` - - - `BetaWebSearchToolResultBlockContent content` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlock:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlock:` - - - `BetaCodeExecutionToolResultBlockContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `class BetaBashCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `class BetaTextEditorCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `class BetaToolSearchToolResultBlock:` - - - `Content content` - - - `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `class BetaMcpToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - The name of the MCP tool - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `class BetaMcpToolResultBlock:` - - - `Content content` - - - `String` - - - `List` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `boolean isError` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `class BetaContainerUploadBlock:` - - Response model for a file uploaded to the container. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `class BetaCompactionBlock:` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `Optional content` - - Summary of compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional contextManagement` - - Context management response. - - Information about context management strategies applied during the request. - - - `List appliedEdits` - - List of context management edits that were applied. - - - `class BetaClearToolUses20250919EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedToolUses` - - Number of tool uses that were cleared. - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - The type of context management edit applied. - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `class BetaClearThinking20251015EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedThinkingTurns` - - Number of thinking turns that were cleared. - - - `JsonValue; type "clear_thinking_20251015"constant` - - The type of context management edit applied. - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Model model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - - Most intelligent model for building agents and coding - - - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` - - Best combination of speed and intelligence - - - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_OPUS_4_5("claude-opus-4-5")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` - - High-performance model for agents and coding - - - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` - - High-performance model for agents and coding - - - `CLAUDE_OPUS_4_1("claude-opus-4-1")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_0("claude-opus-4-0")` - - Powerful model for complex tasks - - - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")` - - Powerful model for complex tasks - - - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")` - - High-performance model with extended thinking - - - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")` - - High-performance model with extended thinking - - - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")` - - Fast and cost-effective model - - - `JsonValue; role "assistant"constant` - - Conversational role of the generated message. - - This will always be `"assistant"`. - - - `ASSISTANT("assistant")` - - - `Optional stopDetails` - - Structured information about a refusal. - - - `Optional category` - - The policy category that triggered the refusal. - - `null` when the refusal doesn't map to a named category. - - - `CYBER("cyber")` - - - `BIO("bio")` - - - `Optional explanation` - - Human-readable explanation of the refusal. - - This text is not guaranteed to be stable. `null` when no explanation is available for the category. - - - `JsonValue; type "refusal"constant` - - - `REFUSAL("refusal")` - - - `Optional stopReason` - - The reason that we stopped. - - This may be one the following values: - - * `"end_turn"`: the model reached a natural stopping point - * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - * `"tool_use"`: the model invoked one or more tools - * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - * `"refusal"`: when streaming classifiers intervene to handle potential policy violations - - In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - - - `END_TURN("end_turn")` - - - `MAX_TOKENS("max_tokens")` - - - `STOP_SEQUENCE("stop_sequence")` - - - `TOOL_USE("tool_use")` - - - `PAUSE_TURN("pause_turn")` - - - `COMPACTION("compaction")` - - - `REFUSAL("refusal")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")` - - - `Optional stopSequence` - - Which custom stop sequence was generated, if any. - - This value will be a non-null string if one of your custom stop sequences was generated. - - - `JsonValue; type "message"constant` - - Object type. - - For Messages, this is always `"message"`. - - - `MESSAGE("message")` - - - `BetaUsage usage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `Optional cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `Optional cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `Optional inferenceGeo` - - The geographic region where inference was performed for this request. - - - `long inputTokens` - - The number of input tokens which were used. - - - `Optional> iterations` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - - - `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - - - `long outputTokens` - - The number of output tokens which were used. - - - `Optional serverToolUse` - - The number of server tool requests. - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - - - `Optional serviceTier` - - If the request used the priority, standard, or batch tier. - - - `STANDARD("standard")` - - - `PRIORITY("priority")` - - - `BATCH("batch")` - - - `Optional speed` - - The inference speed mode used for this request. - - - `STANDARD("standard")` - - - `FAST("fast")` - - - `JsonValue; type "succeeded"constant` - - - `SUCCEEDED("succeeded")` - - - `class BetaMessageBatchErroredResult:` - - - `BetaErrorResponse error` - - - `BetaError error` - - - `class BetaInvalidRequestError:` - - - `String message` - - - `JsonValue; type "invalid_request_error"constant` - - - `INVALID_REQUEST_ERROR("invalid_request_error")` - - - `class BetaAuthenticationError:` - - - `String message` - - - `JsonValue; type "authentication_error"constant` - - - `AUTHENTICATION_ERROR("authentication_error")` - - - `class BetaBillingError:` - - - `String message` - - - `JsonValue; type "billing_error"constant` - - - `BILLING_ERROR("billing_error")` - - - `class BetaPermissionError:` - - - `String message` - - - `JsonValue; type "permission_error"constant` - - - `PERMISSION_ERROR("permission_error")` - - - `class BetaNotFoundError:` - - - `String message` - - - `JsonValue; type "not_found_error"constant` - - - `NOT_FOUND_ERROR("not_found_error")` - - - `class BetaRateLimitError:` - - - `String message` - - - `JsonValue; type "rate_limit_error"constant` - - - `RATE_LIMIT_ERROR("rate_limit_error")` - - - `class BetaGatewayTimeoutError:` - - - `String message` - - - `JsonValue; type "timeout_error"constant` - - - `TIMEOUT_ERROR("timeout_error")` - - - `class BetaApiError:` - - - `String message` - - - `JsonValue; type "api_error"constant` - - - `API_ERROR("api_error")` - - - `class BetaOverloadedError:` - - - `String message` - - - `JsonValue; type "overloaded_error"constant` - - - `OVERLOADED_ERROR("overloaded_error")` - - - `Optional requestId` - - - `JsonValue; type "error"constant` - - - `ERROR("error")` - - - `JsonValue; type "errored"constant` - - - `ERRORED("errored")` - - - `class BetaMessageBatchCanceledResult:` - - - `JsonValue; type "canceled"constant` - - - `CANCELED("canceled")` - - - `class BetaMessageBatchExpiredResult:` - - - `JsonValue; type "expired"constant` - - - `EXPIRED("expired")` - -### Beta Message Batch Succeeded Result - -- `class BetaMessageBatchSucceededResult:` - - - `BetaMessage message` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `Optional container` - - Information about the container used in the request (for the code execution tool) - - - `String id` - - Identifier for the container used in this request - - - `LocalDateTime expiresAt` - - The time at which the container will expire. - - - `Optional> skills` - - Skills loaded in the container - - - `String skillId` - - Skill ID - - - `Type type` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `ANTHROPIC("anthropic")` - - - `CUSTOM("custom")` - - - `String version` - - Skill version or 'latest' for most recent version - - - `List content` - - Content generated by the model. - - This is an array of content blocks, each of which has a `type` that determines its shape. - - Example: - - ```json - [{"type": "text", "text": "Hi, I'm Claude."}] - ``` - - If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. - - For example, if the input `messages` were: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("} - ] - ``` - - Then the response `content` might be: - - ```json - [{"type": "text", "text": "B)"}] - ``` - - - `class BetaTextBlock:` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class BetaThinkingBlock:` - - - `String signature` - - - `String thinking` - - - `JsonValue; type "thinking"constant` - - - `THINKING("thinking")` - - - `class BetaRedactedThinkingBlock:` - - - `String data` - - - `JsonValue; type "redacted_thinking"constant` - - - `REDACTED_THINKING("redacted_thinking")` - - - `class BetaToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - - `JsonValue; type "tool_use"constant` - - - `TOOL_USE("tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaServerToolUseBlock:` - - - `String id` - - - `Input input` - - - `Name name` - - - `WEB_SEARCH("web_search")` - - - `WEB_FETCH("web_fetch")` - - - `CODE_EXECUTION("code_execution")` - - - `BASH_CODE_EXECUTION("bash_code_execution")` - - - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")` - - - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")` - - - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")` - - - `JsonValue; type "server_tool_use"constant` - - - `SERVER_TOOL_USE("server_tool_use")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebSearchToolResultBlock:` - - - `BetaWebSearchToolResultBlockContent content` - - - `class BetaWebSearchToolResultError:` - - - `BetaWebSearchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `QUERY_TOO_LONG("query_too_long")` - - - `REQUEST_TOO_LARGE("request_too_large")` - - - `JsonValue; type "web_search_tool_result_error"constant` - - - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")` - - - `List` - - - `String encryptedContent` - - - `Optional pageAge` - - - `String title` - - - `JsonValue; type "web_search_result"constant` - - - `WEB_SEARCH_RESULT("web_search_result")` - - - `String url` - - - `String toolUseId` - - - `JsonValue; type "web_search_tool_result"constant` - - - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaWebFetchToolResultBlock:` - - - `Content content` - - - `class BetaWebFetchToolResultErrorBlock:` - - - `BetaWebFetchToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `URL_TOO_LONG("url_too_long")` - - - `URL_NOT_ALLOWED("url_not_allowed")` - - - `URL_NOT_ACCESSIBLE("url_not_accessible")` - - - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `MAX_USES_EXCEEDED("max_uses_exceeded")` - - - `UNAVAILABLE("unavailable")` - - - `JsonValue; type "web_fetch_tool_result_error"constant` - - - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")` - - - `class BetaWebFetchBlock:` - - - `BetaDocumentBlock content` - - - `Optional citations` - - Citation configuration for the document - - - `boolean enabled` - - - `Source source` - - - `class BetaBase64PdfSource:` - - - `String data` - - - `JsonValue; mediaType "application/pdf"constant` - - - `APPLICATION_PDF("application/pdf")` - - - `JsonValue; type "base64"constant` - - - `BASE64("base64")` - - - `class BetaPlainTextSource:` - - - `String data` - - - `JsonValue; mediaType "text/plain"constant` - - - `TEXT_PLAIN("text/plain")` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `Optional title` - - The title of the document - - - `JsonValue; type "document"constant` - - - `DOCUMENT("document")` - - - `Optional retrievedAt` - - ISO 8601 timestamp when the content was retrieved - - - `JsonValue; type "web_fetch_result"constant` - - - `WEB_FETCH_RESULT("web_fetch_result")` - - - `String url` - - Fetched content URL - - - `String toolUseId` - - - `JsonValue; type "web_fetch_tool_result"constant` - - - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")` - - - `Optional caller` - - Tool invocation directly from the model. - - - `class BetaDirectCaller:` - - Tool invocation directly from the model. - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class BetaServerToolCaller:` - - Tool invocation generated by a server-side tool. - - - `String toolId` - - - `JsonValue; type "code_execution_20250825"constant` - - - `CODE_EXECUTION_20250825("code_execution_20250825")` - - - `class BetaServerToolCaller20260120:` - - - `String toolId` - - - `JsonValue; type "code_execution_20260120"constant` - - - `CODE_EXECUTION_20260120("code_execution_20260120")` - - - `class BetaCodeExecutionToolResultBlock:` - - - `BetaCodeExecutionToolResultBlockContent content` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `class BetaCodeExecutionToolResultError:` - - - `BetaCodeExecutionToolResultErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `JsonValue; type "code_execution_tool_result_error"constant` - - - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")` - - - `class BetaCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "code_execution_result"constant` - - - `CODE_EXECUTION_RESULT("code_execution_result")` - - - `class BetaEncryptedCodeExecutionResultBlock:` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `List content` - - - `String fileId` - - - `JsonValue; type "code_execution_output"constant` - - - `CODE_EXECUTION_OUTPUT("code_execution_output")` - - - `String encryptedStdout` - - - `long returnCode` - - - `String stderr` - - - `JsonValue; type "encrypted_code_execution_result"constant` - - - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "code_execution_tool_result"constant` - - - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")` - - - `class BetaBashCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaBashCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")` - - - `JsonValue; type "bash_code_execution_tool_result_error"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")` - - - `class BetaBashCodeExecutionResultBlock:` - - - `List content` - - - `String fileId` - - - `JsonValue; type "bash_code_execution_output"constant` - - - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")` - - - `long returnCode` - - - `String stderr` - - - `String stdout` - - - `JsonValue; type "bash_code_execution_result"constant` - - - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")` - - - `String toolUseId` - - - `JsonValue; type "bash_code_execution_tool_result"constant` - - - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")` - - - `class BetaTextEditorCodeExecutionToolResultBlock:` - - - `Content content` - - - `class BetaTextEditorCodeExecutionToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `FILE_NOT_FOUND("file_not_found")` - - - `Optional errorMessage` - - - `JsonValue; type "text_editor_code_execution_tool_result_error"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")` - - - `class BetaTextEditorCodeExecutionViewResultBlock:` - - - `String content` - - - `FileType fileType` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `PDF("pdf")` - - - `Optional numLines` - - - `Optional startLine` - - - `Optional totalLines` - - - `JsonValue; type "text_editor_code_execution_view_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")` - - - `class BetaTextEditorCodeExecutionCreateResultBlock:` - - - `boolean isFileUpdate` - - - `JsonValue; type "text_editor_code_execution_create_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")` - - - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:` - - - `Optional> lines` - - - `Optional newLines` - - - `Optional newStart` - - - `Optional oldLines` - - - `Optional oldStart` - - - `JsonValue; type "text_editor_code_execution_str_replace_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")` - - - `String toolUseId` - - - `JsonValue; type "text_editor_code_execution_tool_result"constant` - - - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")` - - - `class BetaToolSearchToolResultBlock:` - - - `Content content` - - - `class BetaToolSearchToolResultError:` - - - `ErrorCode errorCode` - - - `INVALID_TOOL_INPUT("invalid_tool_input")` - - - `UNAVAILABLE("unavailable")` - - - `TOO_MANY_REQUESTS("too_many_requests")` - - - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")` - - - `Optional errorMessage` - - - `JsonValue; type "tool_search_tool_result_error"constant` - - - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")` - - - `class BetaToolSearchToolSearchResultBlock:` - - - `List toolReferences` - - - `String toolName` - - - `JsonValue; type "tool_reference"constant` - - - `TOOL_REFERENCE("tool_reference")` - - - `JsonValue; type "tool_search_tool_search_result"constant` - - - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")` - - - `String toolUseId` - - - `JsonValue; type "tool_search_tool_result"constant` - - - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")` - - - `class BetaMcpToolUseBlock:` - - - `String id` - - - `Input input` - - - `String name` - - The name of the MCP tool - - - `String serverName` - - The name of the MCP server - - - `JsonValue; type "mcp_tool_use"constant` - - - `MCP_TOOL_USE("mcp_tool_use")` - - - `class BetaMcpToolResultBlock:` - - - `Content content` - - - `String` - - - `List` - - - `Optional> citations` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `class BetaCitationCharLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endCharIndex` - - - `Optional fileId` - - - `long startCharIndex` - - - `JsonValue; type "char_location"constant` - - - `CHAR_LOCATION("char_location")` - - - `class BetaCitationPageLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endPageNumber` - - - `Optional fileId` - - - `long startPageNumber` - - - `JsonValue; type "page_location"constant` - - - `PAGE_LOCATION("page_location")` - - - `class BetaCitationContentBlockLocation:` - - - `String citedText` - - - `long documentIndex` - - - `Optional documentTitle` - - - `long endBlockIndex` - - - `Optional fileId` - - - `long startBlockIndex` - - - `JsonValue; type "content_block_location"constant` - - - `CONTENT_BLOCK_LOCATION("content_block_location")` - - - `class BetaCitationsWebSearchResultLocation:` - - - `String citedText` - - - `String encryptedIndex` - - - `Optional title` - - - `JsonValue; type "web_search_result_location"constant` - - - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")` - - - `String url` - - - `class BetaCitationSearchResultLocation:` - - - `String citedText` - - - `long endBlockIndex` - - - `long searchResultIndex` - - - `String source` - - - `long startBlockIndex` - - - `Optional title` - - - `JsonValue; type "search_result_location"constant` - - - `SEARCH_RESULT_LOCATION("search_result_location")` - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `boolean isError` - - - `String toolUseId` - - - `JsonValue; type "mcp_tool_result"constant` - - - `MCP_TOOL_RESULT("mcp_tool_result")` - - - `class BetaContainerUploadBlock:` - - Response model for a file uploaded to the container. - - - `String fileId` - - - `JsonValue; type "container_upload"constant` - - - `CONTAINER_UPLOAD("container_upload")` - - - `class BetaCompactionBlock:` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `Optional content` - - Summary of compacted content, or null if compaction failed - - - `JsonValue; type "compaction"constant` - - - `COMPACTION("compaction")` - - - `Optional contextManagement` - - Context management response. - - Information about context management strategies applied during the request. - - - `List appliedEdits` - - List of context management edits that were applied. - - - `class BetaClearToolUses20250919EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedToolUses` - - Number of tool uses that were cleared. - - - `JsonValue; type "clear_tool_uses_20250919"constant` - - The type of context management edit applied. - - - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")` - - - `class BetaClearThinking20251015EditResponse:` - - - `long clearedInputTokens` - - Number of input tokens cleared by this edit. - - - `long clearedThinkingTurns` - - Number of thinking turns that were cleared. - - - `JsonValue; type "clear_thinking_20251015"constant` - - The type of context management edit applied. - - - `CLEAR_THINKING_20251015("clear_thinking_20251015")` - - - `Model model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - - Most intelligent model for building agents and coding - - - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` - - Best combination of speed and intelligence - - - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` - - Fastest model with near-frontier intelligence - - - `CLAUDE_OPUS_4_5("claude-opus-4-5")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` - - Premium model combining maximum intelligence with practical performance - - - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` - - High-performance model for agents and coding - - - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` - - High-performance model for agents and coding - - - `CLAUDE_OPUS_4_1("claude-opus-4-1")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")` - - Exceptional model for specialized complex tasks - - - `CLAUDE_OPUS_4_0("claude-opus-4-0")` - - Powerful model for complex tasks - - - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")` - - Powerful model for complex tasks - - - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")` - - High-performance model with extended thinking - - - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")` - - High-performance model with extended thinking - - - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")` - - Fast and cost-effective model - - - `JsonValue; role "assistant"constant` - - Conversational role of the generated message. - - This will always be `"assistant"`. - - - `ASSISTANT("assistant")` - - - `Optional stopDetails` - - Structured information about a refusal. - - - `Optional category` - - The policy category that triggered the refusal. - - `null` when the refusal doesn't map to a named category. - - - `CYBER("cyber")` - - - `BIO("bio")` - - - `Optional explanation` - - Human-readable explanation of the refusal. - - This text is not guaranteed to be stable. `null` when no explanation is available for the category. - - - `JsonValue; type "refusal"constant` - - - `REFUSAL("refusal")` - - - `Optional stopReason` - - The reason that we stopped. - - This may be one the following values: - - * `"end_turn"`: the model reached a natural stopping point - * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - * `"tool_use"`: the model invoked one or more tools - * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - * `"refusal"`: when streaming classifiers intervene to handle potential policy violations - - In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - - - `END_TURN("end_turn")` - - - `MAX_TOKENS("max_tokens")` - - - `STOP_SEQUENCE("stop_sequence")` - - - `TOOL_USE("tool_use")` - - - `PAUSE_TURN("pause_turn")` - - - `COMPACTION("compaction")` - - - `REFUSAL("refusal")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")` - - - `Optional stopSequence` - - Which custom stop sequence was generated, if any. - - This value will be a non-null string if one of your custom stop sequences was generated. - - - `JsonValue; type "message"constant` - - Object type. - - For Messages, this is always `"message"`. - - - `MESSAGE("message")` - - - `BetaUsage usage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `Optional cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `Optional cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `Optional inferenceGeo` - - The geographic region where inference was performed for this request. - - - `long inputTokens` - - The number of input tokens which were used. - - - `Optional> iterations` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `class BetaMessageIterationUsage:` - - Token usage for a sampling iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "message"constant` - - Usage for a sampling iteration - - - `MESSAGE("message")` - - - `class BetaCompactionIterationUsage:` - - Token usage for a compaction iteration. - - - `Optional cacheCreation` - - Breakdown of cached tokens by TTL - - - `long ephemeral1hInputTokens` - - The number of input tokens used to create the 1 hour cache entry. - - - `long ephemeral5mInputTokens` - - The number of input tokens used to create the 5 minute cache entry. - - - `long cacheCreationInputTokens` - - The number of input tokens used to create the cache entry. - - - `long cacheReadInputTokens` - - The number of input tokens read from the cache. - - - `long inputTokens` - - The number of input tokens which were used. - - - `long outputTokens` - - The number of output tokens which were used. - - - `JsonValue; type "compaction"constant` - - Usage for a compaction iteration - - - `COMPACTION("compaction")` - - - `long outputTokens` - - The number of output tokens which were used. - - - `Optional serverToolUse` - - The number of server tool requests. - - - `long webFetchRequests` - - The number of web fetch tool requests. - - - `long webSearchRequests` - - The number of web search tool requests. - - - `Optional serviceTier` - - If the request used the priority, standard, or batch tier. - - - `STANDARD("standard")` - - - `PRIORITY("priority")` - - - `BATCH("batch")` - - - `Optional speed` - - The inference speed mode used for this request. - - - `STANDARD("standard")` - - - `FAST("fast")` - - - `JsonValue; type "succeeded"constant` - - - `SUCCEEDED("succeeded")` - -# Files - -## Upload - -`FileMetadata beta().files().upload(FileUploadParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - -**post** `/v1/files` - -Upload File - -### Parameters - -- `FileUploadParams params` - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - - `String file` - - The file to upload - -### Returns - -- `class FileMetadata:` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `LocalDateTime createdAt` - - RFC 3339 datetime string representing when the file was created. - - - `String filename` - - Original filename of the uploaded file. - - - `String mimeType` - - MIME type of the file. - - - `long sizeBytes` - - Size of the file in bytes. - - - `JsonValue; type "file"constant` - - Object type. - - For files, this is always `"file"`. - - - `FILE("file")` - - - `Optional downloadable` - - Whether the file can be downloaded. - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.files.FileMetadata; -import com.anthropic.models.beta.files.FileUploadParams; -import java.io.ByteArrayInputStream; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - FileUploadParams params = FileUploadParams.builder() - .file(new ByteArrayInputStream("Example data".getBytes())) - .build(); - FileMetadata fileMetadata = client.beta().files().upload(params); - } -} -``` - -## List - -`FileListPage beta().files().list(FileListParamsparams = FileListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/files` - -List Files - -### Parameters - -- `FileListParams params` - - - `Optional afterId` - - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - - - `Optional beforeId` - - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - - - `Optional limit` - - Number of items to return per page. - - Defaults to `20`. Ranges from `1` to `1000`. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class FileMetadata:` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `LocalDateTime createdAt` - - RFC 3339 datetime string representing when the file was created. - - - `String filename` - - Original filename of the uploaded file. - - - `String mimeType` - - MIME type of the file. - - - `long sizeBytes` - - Size of the file in bytes. - - - `JsonValue; type "file"constant` - - Object type. - - For files, this is always `"file"`. - - - `FILE("file")` - - - `Optional downloadable` - - Whether the file can be downloaded. - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.files.FileListPage; -import com.anthropic.models.beta.files.FileListParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - FileListPage page = client.beta().files().list(); - } -} -``` - -## Download - -`HttpResponse beta().files().download(FileDownloadParamsparams = FileDownloadParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/files/{file_id}/content` - -Download File - -### Parameters - -- `FileDownloadParams params` - - - `Optional fileId` - - ID of the File. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.core.http.HttpResponse; -import com.anthropic.models.beta.files.FileDownloadParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - HttpResponse response = client.beta().files().download("file_id"); - } -} -``` - -## Retrieve Metadata - -`FileMetadata beta().files().retrieveMetadata(FileRetrieveMetadataParamsparams = FileRetrieveMetadataParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/files/{file_id}` - -Get File Metadata - -### Parameters - -- `FileRetrieveMetadataParams params` - - - `Optional fileId` - - ID of the File. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class FileMetadata:` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `LocalDateTime createdAt` - - RFC 3339 datetime string representing when the file was created. - - - `String filename` - - Original filename of the uploaded file. - - - `String mimeType` - - MIME type of the file. - - - `long sizeBytes` - - Size of the file in bytes. - - - `JsonValue; type "file"constant` - - Object type. - - For files, this is always `"file"`. - - - `FILE("file")` - - - `Optional downloadable` - - Whether the file can be downloaded. - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.files.FileMetadata; -import com.anthropic.models.beta.files.FileRetrieveMetadataParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - FileMetadata fileMetadata = client.beta().files().retrieveMetadata("file_id"); - } -} -``` - -## Delete - -`DeletedFile beta().files().delete(FileDeleteParamsparams = FileDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**delete** `/v1/files/{file_id}` - -Delete File - -### Parameters - -- `FileDeleteParams params` - - - `Optional fileId` - - ID of the File. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class DeletedFile:` - - - `String id` - - ID of the deleted file. - - - `Optional type` - - Deleted object type. - - For file deletion, this is always `"file_deleted"`. - - - `FILE_DELETED("file_deleted")` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.files.DeletedFile; -import com.anthropic.models.beta.files.FileDeleteParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - DeletedFile deletedFile = client.beta().files().delete("file_id"); - } -} -``` - -## Domain Types - -### Deleted File - -- `class DeletedFile:` - - - `String id` - - ID of the deleted file. - - - `Optional type` - - Deleted object type. - - For file deletion, this is always `"file_deleted"`. - - - `FILE_DELETED("file_deleted")` - -### File Metadata - -- `class FileMetadata:` - - - `String id` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `LocalDateTime createdAt` - - RFC 3339 datetime string representing when the file was created. - - - `String filename` - - Original filename of the uploaded file. - - - `String mimeType` - - MIME type of the file. - - - `long sizeBytes` - - Size of the file in bytes. - - - `JsonValue; type "file"constant` - - Object type. - - For files, this is always `"file"`. - - - `FILE("file")` - - - `Optional downloadable` - - Whether the file can be downloaded. - -# Skills - -## Create - -`SkillCreateResponse beta().skills().create(SkillCreateParamsparams = SkillCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**post** `/v1/skills` - -Create Skill - -### Parameters - -- `SkillCreateParams params` - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - - `Optional displayTitle` - - Display title for the skill. - - This is a human-readable label that is not included in the prompt sent to the model. - - - `Optional> files` - - Files to upload for the skill. - - All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. - -### Returns - -- `class SkillCreateResponse:` - - - `String id` - - Unique identifier for the skill. - - The format and length of IDs may change over time. - - - `String createdAt` - - ISO 8601 timestamp of when the skill was created. - - - `Optional displayTitle` - - Display title for the skill. - - This is a human-readable label that is not included in the prompt sent to the model. - - - `Optional latestVersion` - - The latest version identifier for the skill. - - This represents the most recent version of the skill that has been created. - - - `String source` - - Source of the skill. - - This may be one of the following values: - - * `"custom"`: the skill was created by a user - * `"anthropic"`: the skill was created by Anthropic - - - `String type` - - Object type. - - For Skills, this is always `"skill"`. - - - `String updatedAt` - - ISO 8601 timestamp of when the skill was last updated. - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.skills.SkillCreateParams; -import com.anthropic.models.beta.skills.SkillCreateResponse; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - SkillCreateResponse skill = client.beta().skills().create(); - } -} -``` - -## List - -`SkillListPage beta().skills().list(SkillListParamsparams = SkillListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/skills` - -List Skills - -### Parameters - -- `SkillListParams params` - - - `Optional limit` - - Number of results to return per page. - - Maximum value is 100. Defaults to 20. - - - `Optional page` - - Pagination token for fetching a specific page of results. - - Pass the value from a previous response's `next_page` field to get the next page of results. - - - `Optional source` - - Filter skills by source. - - If provided, only skills from the specified source will be returned: - - * `"custom"`: only return user-created skills - * `"anthropic"`: only return Anthropic-created skills - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class SkillListResponse:` - - - `String id` - - Unique identifier for the skill. - - The format and length of IDs may change over time. - - - `String createdAt` - - ISO 8601 timestamp of when the skill was created. - - - `Optional displayTitle` - - Display title for the skill. - - This is a human-readable label that is not included in the prompt sent to the model. - - - `Optional latestVersion` - - The latest version identifier for the skill. - - This represents the most recent version of the skill that has been created. - - - `String source` - - Source of the skill. - - This may be one of the following values: - - * `"custom"`: the skill was created by a user - * `"anthropic"`: the skill was created by Anthropic - - - `String type` - - Object type. - - For Skills, this is always `"skill"`. - - - `String updatedAt` - - ISO 8601 timestamp of when the skill was last updated. - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.skills.SkillListPage; -import com.anthropic.models.beta.skills.SkillListParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - SkillListPage page = client.beta().skills().list(); - } -} -``` - -## Retrieve - -`SkillRetrieveResponse beta().skills().retrieve(SkillRetrieveParamsparams = SkillRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/skills/{skill_id}` - -Get Skill - -### Parameters - -- `SkillRetrieveParams params` - - - `Optional skillId` - - Unique identifier for the skill. - - The format and length of IDs may change over time. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class SkillRetrieveResponse:` - - - `String id` - - Unique identifier for the skill. - - The format and length of IDs may change over time. - - - `String createdAt` - - ISO 8601 timestamp of when the skill was created. - - - `Optional displayTitle` - - Display title for the skill. - - This is a human-readable label that is not included in the prompt sent to the model. - - - `Optional latestVersion` - - The latest version identifier for the skill. - - This represents the most recent version of the skill that has been created. - - - `String source` - - Source of the skill. - - This may be one of the following values: - - * `"custom"`: the skill was created by a user - * `"anthropic"`: the skill was created by Anthropic - - - `String type` - - Object type. - - For Skills, this is always `"skill"`. - - - `String updatedAt` - - ISO 8601 timestamp of when the skill was last updated. - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.skills.SkillRetrieveParams; -import com.anthropic.models.beta.skills.SkillRetrieveResponse; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - SkillRetrieveResponse skill = client.beta().skills().retrieve("skill_id"); - } -} -``` - -## Delete - -`SkillDeleteResponse beta().skills().delete(SkillDeleteParamsparams = SkillDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**delete** `/v1/skills/{skill_id}` - -Delete Skill - -### Parameters - -- `SkillDeleteParams params` - - - `Optional skillId` - - Unique identifier for the skill. - - The format and length of IDs may change over time. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class SkillDeleteResponse:` - - - `String id` - - Unique identifier for the skill. - - The format and length of IDs may change over time. - - - `String type` - - Deleted object type. - - For Skills, this is always `"skill_deleted"`. - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.skills.SkillDeleteParams; -import com.anthropic.models.beta.skills.SkillDeleteResponse; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - SkillDeleteResponse skill = client.beta().skills().delete("skill_id"); - } -} -``` - -# Versions - -## Create - -`VersionCreateResponse beta().skills().versions().create(VersionCreateParamsparams = VersionCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**post** `/v1/skills/{skill_id}/versions` - -Create Skill Version - -### Parameters - -- `VersionCreateParams params` - - - `Optional skillId` - - Unique identifier for the skill. - - The format and length of IDs may change over time. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - - `Optional> files` - - Files to upload for the skill. - - All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. - -### Returns - -- `class VersionCreateResponse:` - - - `String id` - - Unique identifier for the skill version. - - The format and length of IDs may change over time. - - - `String createdAt` - - ISO 8601 timestamp of when the skill version was created. - - - `String description` - - Description of the skill version. - - This is extracted from the SKILL.md file in the skill upload. - - - `String directory` - - Directory name of the skill version. - - This is the top-level directory name that was extracted from the uploaded files. - - - `String name` - - Human-readable name of the skill version. - - This is extracted from the SKILL.md file in the skill upload. - - - `String skillId` - - Identifier for the skill that this version belongs to. - - - `String type` - - Object type. - - For Skill Versions, this is always `"skill_version"`. - - - `String version` - - Version identifier for the skill. - - Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.skills.versions.VersionCreateParams; -import com.anthropic.models.beta.skills.versions.VersionCreateResponse; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - VersionCreateResponse version = client.beta().skills().versions().create("skill_id"); - } -} -``` - -## List - -`VersionListPage beta().skills().versions().list(VersionListParamsparams = VersionListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/skills/{skill_id}/versions` - -List Skill Versions - -### Parameters - -- `VersionListParams params` - - - `Optional skillId` - - Unique identifier for the skill. - - The format and length of IDs may change over time. - - - `Optional limit` - - Number of items to return per page. - - Defaults to `20`. Ranges from `1` to `1000`. - - - `Optional page` - - Optionally set to the `next_page` token from the previous response. - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class VersionListResponse:` - - - `String id` - - Unique identifier for the skill version. - - The format and length of IDs may change over time. - - - `String createdAt` - - ISO 8601 timestamp of when the skill version was created. - - - `String description` - - Description of the skill version. - - This is extracted from the SKILL.md file in the skill upload. - - - `String directory` - - Directory name of the skill version. - - This is the top-level directory name that was extracted from the uploaded files. - - - `String name` - - Human-readable name of the skill version. - - This is extracted from the SKILL.md file in the skill upload. - - - `String skillId` - - Identifier for the skill that this version belongs to. - - - `String type` - - Object type. - - For Skill Versions, this is always `"skill_version"`. - - - `String version` - - Version identifier for the skill. - - Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.skills.versions.VersionListPage; -import com.anthropic.models.beta.skills.versions.VersionListParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - VersionListPage page = client.beta().skills().versions().list("skill_id"); - } -} -``` - -## Retrieve - -`VersionRetrieveResponse beta().skills().versions().retrieve(VersionRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/skills/{skill_id}/versions/{version}` - -Get Skill Version - -### Parameters - -- `VersionRetrieveParams params` - - - `String skillId` - - Unique identifier for the skill. - - The format and length of IDs may change over time. - - - `Optional version` - - Version identifier for the skill. - - Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class VersionRetrieveResponse:` - - - `String id` - - Unique identifier for the skill version. - - The format and length of IDs may change over time. - - - `String createdAt` - - ISO 8601 timestamp of when the skill version was created. - - - `String description` - - Description of the skill version. - - This is extracted from the SKILL.md file in the skill upload. - - - `String directory` - - Directory name of the skill version. - - This is the top-level directory name that was extracted from the uploaded files. - - - `String name` - - Human-readable name of the skill version. - - This is extracted from the SKILL.md file in the skill upload. - - - `String skillId` - - Identifier for the skill that this version belongs to. - - - `String type` - - Object type. - - For Skill Versions, this is always `"skill_version"`. - - - `String version` - - Version identifier for the skill. - - Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.skills.versions.VersionRetrieveParams; -import com.anthropic.models.beta.skills.versions.VersionRetrieveResponse; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - VersionRetrieveParams params = VersionRetrieveParams.builder() - .skillId("skill_id") - .version("version") - .build(); - VersionRetrieveResponse version = client.beta().skills().versions().retrieve(params); - } -} -``` - -## Delete - -`VersionDeleteResponse beta().skills().versions().delete(VersionDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - -**delete** `/v1/skills/{skill_id}/versions/{version}` - -Delete Skill Version - -### Parameters - -- `VersionDeleteParams params` - - - `String skillId` - - Unique identifier for the skill. - - The format and length of IDs may change over time. - - - `Optional version` - - Version identifier for the skill. - - Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class VersionDeleteResponse:` - - - `String id` - - Version identifier for the skill. - - Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - - - `String type` - - Deleted object type. - - For Skill Versions, this is always `"skill_version_deleted"`. - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.skills.versions.VersionDeleteParams; -import com.anthropic.models.beta.skills.versions.VersionDeleteResponse; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - VersionDeleteParams params = VersionDeleteParams.builder() - .skillId("skill_id") - .version("version") - .build(); - VersionDeleteResponse version = client.beta().skills().versions().delete(params); - } -} -``` - -# User Profiles - -## Create - -`BetaUserProfile beta().userProfiles().create(UserProfileCreateParamsparams = UserProfileCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**post** `/v1/user_profiles` - -Create User Profile - -### Parameters - -- `UserProfileCreateParams params` - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - - `Optional externalId` - - - `Optional metadata` - - Free-form key-value data to attach to this user profile. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. Values must be non-empty strings. - -### Returns - -- `class BetaUserProfile:` - - - `String id` - - - `LocalDateTime createdAt` - - A timestamp in RFC 3339 format - - - `Metadata metadata` - - - `TrustGrants trustGrants` - - - `String status` - - - `String type` - - - `LocalDateTime updatedAt` - - A timestamp in RFC 3339 format - - - `Optional externalId` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.userprofiles.BetaUserProfile; -import com.anthropic.models.beta.userprofiles.UserProfileCreateParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - BetaUserProfile betaUserProfile = client.beta().userProfiles().create(); - } -} -``` - -## List - -`UserProfileListPage beta().userProfiles().list(UserProfileListParamsparams = UserProfileListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/user_profiles` - -List User Profiles - -### Parameters - -- `UserProfileListParams params` - - - `Optional limit` - - Query parameter for limit - - - `Optional order` - - Query parameter for order - - - `ASC("asc")` - - - `DESC("desc")` - - - `Optional page` - - Query parameter for page - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class BetaUserProfile:` - - - `String id` - - - `LocalDateTime createdAt` - - A timestamp in RFC 3339 format - - - `Metadata metadata` - - - `TrustGrants trustGrants` - - - `String status` - - - `String type` - - - `LocalDateTime updatedAt` - - A timestamp in RFC 3339 format - - - `Optional externalId` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.userprofiles.UserProfileListPage; -import com.anthropic.models.beta.userprofiles.UserProfileListParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - UserProfileListPage page = client.beta().userProfiles().list(); - } -} -``` - -## Retrieve - -`BetaUserProfile beta().userProfiles().retrieve(UserProfileRetrieveParamsparams = UserProfileRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**get** `/v1/user_profiles/{id}` - -Get User Profile - -### Parameters - -- `UserProfileRetrieveParams params` - - - `Optional id` - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class BetaUserProfile:` - - - `String id` - - - `LocalDateTime createdAt` - - A timestamp in RFC 3339 format - - - `Metadata metadata` - - - `TrustGrants trustGrants` - - - `String status` - - - `String type` - - - `LocalDateTime updatedAt` - - A timestamp in RFC 3339 format - - - `Optional externalId` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.userprofiles.BetaUserProfile; -import com.anthropic.models.beta.userprofiles.UserProfileRetrieveParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - BetaUserProfile betaUserProfile = client.beta().userProfiles().retrieve("id"); - } -} -``` - -## Update - -`BetaUserProfile beta().userProfiles().update(UserProfileUpdateParamsparams = UserProfileUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**post** `/v1/user_profiles/{id}` - -Update User Profile - -### Parameters - -- `UserProfileUpdateParams params` - - - `Optional id` - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - - `Optional externalId` - - - `Optional metadata` - - Key-value pairs to merge into the stored metadata. Keys provided overwrite existing values. To remove a key, set its value to an empty string. Keys not provided are left unchanged. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. - -### Returns - -- `class BetaUserProfile:` - - - `String id` - - - `LocalDateTime createdAt` - - A timestamp in RFC 3339 format - - - `Metadata metadata` - - - `TrustGrants trustGrants` - - - `String status` - - - `String type` - - - `LocalDateTime updatedAt` - - A timestamp in RFC 3339 format - - - `Optional externalId` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.userprofiles.BetaUserProfile; -import com.anthropic.models.beta.userprofiles.UserProfileUpdateParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - BetaUserProfile betaUserProfile = client.beta().userProfiles().update("id"); - } -} -``` - -## Create Enrollment URL - -`BetaUserProfileEnrollmentUrl beta().userProfiles().createEnrollmentUrl(UserProfileCreateEnrollmentUrlParamsparams = UserProfileCreateEnrollmentUrlParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - -**post** `/v1/user_profiles/{id}/enrollment_url` - -Create Enrollment URL - -### Parameters - -- `UserProfileCreateEnrollmentUrlParams params` - - - `Optional id` - - - `Optional> betas` - - Optional header to specify the beta version(s) you want to use. - - - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` - - - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` - - - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` - - - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` - - - `PDFS_2024_09_25("pdfs-2024-09-25")` - - - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` - - - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` - - - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` - - - `FILES_API_2025_04_14("files-api-2025-04-14")` - - - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` - - - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` - - - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` - - - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` - - - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` - - - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` - - - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` - - - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` - - - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` - - - `SKILLS_2025_10_02("skills-2025-10-02")` - - - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` - - - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - -### Returns - -- `class BetaUserProfileEnrollmentUrl:` - - - `LocalDateTime expiresAt` - - A timestamp in RFC 3339 format - - - `String type` - - - `String url` - -### Example - -```java -package com.anthropic.example; - -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.beta.userprofiles.BetaUserProfileEnrollmentUrl; -import com.anthropic.models.beta.userprofiles.UserProfileCreateEnrollmentUrlParams; - -public final class Main { - private Main() {} - - public static void main(String[] args) { - AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - - BetaUserProfileEnrollmentUrl betaUserProfileEnrollmentUrl = client.beta().userProfiles().createEnrollmentUrl("id"); - } -} -``` - -## Domain Types - -### Beta User Profile - -- `class BetaUserProfile:` - - - `String id` - - - `LocalDateTime createdAt` - - A timestamp in RFC 3339 format - - - `Metadata metadata` - - - `TrustGrants trustGrants` - - - `String status` - - - `String type` - - - `LocalDateTime updatedAt` - - A timestamp in RFC 3339 format - - - `Optional externalId` - -### Beta User Profile Enrollment URL - -- `class BetaUserProfileEnrollmentUrl:` - - - `LocalDateTime expiresAt` - - A timestamp in RFC 3339 format - - - `String type` - - - `String url` - -### Beta User Profile Trust Grant - -- `class BetaUserProfileTrustGrant:` - - - `String status` +Not Found - Claude API Docs
                                                                                              \ No newline at end of file diff --git a/content/en/api/java/beta/agents.md b/content/en/api/java/beta/agents.md new file mode 100644 index 000000000..d8116ead7 --- /dev/null +++ b/content/en/api/java/beta/agents.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                \ No newline at end of file diff --git a/content/en/api/java/beta/agents/archive.md b/content/en/api/java/beta/agents/archive.md new file mode 100644 index 000000000..c4899b5fa --- /dev/null +++ b/content/en/api/java/beta/agents/archive.md @@ -0,0 +1,370 @@ +## Archive + +`BetaManagedAgentsAgent beta().agents().archive(AgentArchiveParamsparams = AgentArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `AgentArchiveParams params` + + - `Optional agentId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `String id` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `Metadata metadata` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `long version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.agents.AgentArchiveParams; +import com.anthropic.models.beta.agents.BetaManagedAgentsAgent; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsAgent betaManagedAgentsAgent = client.beta().agents().archive("agent_011CZkYpogX7uDKUyvBTophP"); + } +} +``` diff --git a/content/en/api/java/beta/agents/create.md b/content/en/api/java/beta/agents/create.md new file mode 100644 index 000000000..db49382cc --- /dev/null +++ b/content/en/api/java/beta/agents/create.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                  \ No newline at end of file diff --git a/content/en/api/java/beta/agents/list.md b/content/en/api/java/beta/agents/list.md new file mode 100644 index 000000000..8b527699f --- /dev/null +++ b/content/en/api/java/beta/agents/list.md @@ -0,0 +1,388 @@ +## List + +`AgentListPage beta().agents().list(AgentListParamsparams = AgentListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `AgentListParams params` + + - `Optional createdAtGte` + + Return agents created at or after this time (inclusive). + + - `Optional createdAtLte` + + Return agents created at or before this time (inclusive). + + - `Optional includeArchived` + + Include archived agents in results. Defaults to false. + + - `Optional limit` + + Maximum results per page. Default 20, maximum 100. + + - `Optional page` + + Opaque pagination cursor from a previous response. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `String id` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `Metadata metadata` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `long version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.agents.AgentListPage; +import com.anthropic.models.beta.agents.AgentListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + AgentListPage page = client.beta().agents().list(); + } +} +``` diff --git a/content/en/api/java/beta/agents/retrieve.md b/content/en/api/java/beta/agents/retrieve.md new file mode 100644 index 000000000..a91147c50 --- /dev/null +++ b/content/en/api/java/beta/agents/retrieve.md @@ -0,0 +1,374 @@ +## Retrieve + +`BetaManagedAgentsAgent beta().agents().retrieve(AgentRetrieveParamsparams = AgentRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `AgentRetrieveParams params` + + - `Optional agentId` + + - `Optional version` + + Agent version. Omit for the most recent version. Must be at least 1 if specified. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `String id` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `Metadata metadata` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `long version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.agents.AgentRetrieveParams; +import com.anthropic.models.beta.agents.BetaManagedAgentsAgent; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsAgent betaManagedAgentsAgent = client.beta().agents().retrieve("agent_011CZkYpogX7uDKUyvBTophP"); + } +} +``` diff --git a/content/en/api/java/beta/agents/update.md b/content/en/api/java/beta/agents/update.md new file mode 100644 index 000000000..52c05243d --- /dev/null +++ b/content/en/api/java/beta/agents/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                    \ No newline at end of file diff --git a/content/en/api/java/beta/agents/versions.md b/content/en/api/java/beta/agents/versions.md new file mode 100644 index 000000000..bf2a18b61 --- /dev/null +++ b/content/en/api/java/beta/agents/versions.md @@ -0,0 +1,380 @@ +# Versions + +## List + +`VersionListPage beta().agents().versions().list(VersionListParamsparams = VersionListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `VersionListParams params` + + - `Optional agentId` + + - `Optional limit` + + Maximum results per page. Default 20, maximum 100. + + - `Optional page` + + Opaque pagination cursor. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `String id` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `Metadata metadata` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `long version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.agents.versions.VersionListPage; +import com.anthropic.models.beta.agents.versions.VersionListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + VersionListPage page = client.beta().agents().versions().list("agent_011CZkYpogX7uDKUyvBTophP"); + } +} +``` diff --git a/content/en/api/java/beta/agents/versions/list.md b/content/en/api/java/beta/agents/versions/list.md new file mode 100644 index 000000000..224c3c229 --- /dev/null +++ b/content/en/api/java/beta/agents/versions/list.md @@ -0,0 +1,378 @@ +## List + +`VersionListPage beta().agents().versions().list(VersionListParamsparams = VersionListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `VersionListParams params` + + - `Optional agentId` + + - `Optional limit` + + Maximum results per page. Default 20, maximum 100. + + - `Optional page` + + Opaque pagination cursor. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsAgent:` + + A Managed Agents `agent`. + + - `String id` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `Metadata metadata` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `long version` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.agents.versions.VersionListPage; +import com.anthropic.models.beta.agents.versions.VersionListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + VersionListPage page = client.beta().agents().versions().list("agent_011CZkYpogX7uDKUyvBTophP"); + } +} +``` diff --git a/content/en/api/java/beta/environments.md b/content/en/api/java/beta/environments.md new file mode 100644 index 000000000..73933ebbd --- /dev/null +++ b/content/en/api/java/beta/environments.md @@ -0,0 +1,1599 @@ +# Environments + +## Create + +`BetaEnvironment beta().environments().create(EnvironmentCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `EnvironmentCreateParams params` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `String name` + + Human-readable name for the environment + + - `Optional config` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Optional description` + + Optional description of the environment + + - `Optional metadata` + + User-provided metadata key-value pairs + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `String id` + + Environment identifier (e.g., 'env_...') + + - `Optional archivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `BetaCloudConfig config` + + `cloud` environment configuration. + + - `Networking networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `BetaPackages packages` + + Package manager configuration. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + + - `String createdAt` + + RFC 3339 timestamp when environment was created + + - `String description` + + User-provided description for the environment + + - `Metadata metadata` + + User-provided metadata key-value pairs + + - `String name` + + Human-readable name for the environment + + - `JsonValue; type "environment"constant` + + The type of object (always 'environment') + + - `ENVIRONMENT("environment")` + + - `String updatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.environments.BetaEnvironment; +import com.anthropic.models.beta.environments.EnvironmentCreateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + EnvironmentCreateParams params = EnvironmentCreateParams.builder() + .name("python-data-analysis") + .build(); + BetaEnvironment betaEnvironment = client.beta().environments().create(params); + } +} +``` + +## List + +`EnvironmentListPage beta().environments().list(EnvironmentListParamsparams = EnvironmentListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `EnvironmentListParams params` + + - `Optional includeArchived` + + Include archived environments in the response + + - `Optional limit` + + Maximum number of environments to return + + - `Optional page` + + Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `String id` + + Environment identifier (e.g., 'env_...') + + - `Optional archivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `BetaCloudConfig config` + + `cloud` environment configuration. + + - `Networking networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `BetaPackages packages` + + Package manager configuration. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + + - `String createdAt` + + RFC 3339 timestamp when environment was created + + - `String description` + + User-provided description for the environment + + - `Metadata metadata` + + User-provided metadata key-value pairs + + - `String name` + + Human-readable name for the environment + + - `JsonValue; type "environment"constant` + + The type of object (always 'environment') + + - `ENVIRONMENT("environment")` + + - `String updatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.environments.EnvironmentListPage; +import com.anthropic.models.beta.environments.EnvironmentListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + EnvironmentListPage page = client.beta().environments().list(); + } +} +``` + +## Retrieve + +`BetaEnvironment beta().environments().retrieve(EnvironmentRetrieveParamsparams = EnvironmentRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `EnvironmentRetrieveParams params` + + - `Optional environmentId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `String id` + + Environment identifier (e.g., 'env_...') + + - `Optional archivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `BetaCloudConfig config` + + `cloud` environment configuration. + + - `Networking networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `BetaPackages packages` + + Package manager configuration. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + + - `String createdAt` + + RFC 3339 timestamp when environment was created + + - `String description` + + User-provided description for the environment + + - `Metadata metadata` + + User-provided metadata key-value pairs + + - `String name` + + Human-readable name for the environment + + - `JsonValue; type "environment"constant` + + The type of object (always 'environment') + + - `ENVIRONMENT("environment")` + + - `String updatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.environments.BetaEnvironment; +import com.anthropic.models.beta.environments.EnvironmentRetrieveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaEnvironment betaEnvironment = client.beta().environments().retrieve("env_011CZkZ9X2dpNyB7HsEFoRfW"); + } +} +``` + +## Update + +`BetaEnvironment beta().environments().update(EnvironmentUpdateParamsparams = EnvironmentUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `EnvironmentUpdateParams params` + + - `Optional environmentId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Optional config` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Optional description` + + Updated description of the environment + + - `Optional metadata` + + User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + + - `Optional name` + + Updated name for the environment + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `String id` + + Environment identifier (e.g., 'env_...') + + - `Optional archivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `BetaCloudConfig config` + + `cloud` environment configuration. + + - `Networking networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `BetaPackages packages` + + Package manager configuration. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + + - `String createdAt` + + RFC 3339 timestamp when environment was created + + - `String description` + + User-provided description for the environment + + - `Metadata metadata` + + User-provided metadata key-value pairs + + - `String name` + + Human-readable name for the environment + + - `JsonValue; type "environment"constant` + + The type of object (always 'environment') + + - `ENVIRONMENT("environment")` + + - `String updatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.environments.BetaEnvironment; +import com.anthropic.models.beta.environments.EnvironmentUpdateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaEnvironment betaEnvironment = client.beta().environments().update("env_011CZkZ9X2dpNyB7HsEFoRfW"); + } +} +``` + +## Delete + +`BetaEnvironmentDeleteResponse beta().environments().delete(EnvironmentDeleteParamsparams = EnvironmentDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `EnvironmentDeleteParams params` + + - `Optional environmentId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaEnvironmentDeleteResponse:` + + Response after deleting an environment. + + - `String id` + + Environment identifier + + - `JsonValue; type "environment_deleted"constant` + + The type of response + + - `ENVIRONMENT_DELETED("environment_deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.environments.BetaEnvironmentDeleteResponse; +import com.anthropic.models.beta.environments.EnvironmentDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaEnvironmentDeleteResponse betaEnvironmentDeleteResponse = client.beta().environments().delete("env_011CZkZ9X2dpNyB7HsEFoRfW"); + } +} +``` + +## Archive + +`BetaEnvironment beta().environments().archive(EnvironmentArchiveParamsparams = EnvironmentArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `EnvironmentArchiveParams params` + + - `Optional environmentId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `String id` + + Environment identifier (e.g., 'env_...') + + - `Optional archivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `BetaCloudConfig config` + + `cloud` environment configuration. + + - `Networking networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `BetaPackages packages` + + Package manager configuration. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + + - `String createdAt` + + RFC 3339 timestamp when environment was created + + - `String description` + + User-provided description for the environment + + - `Metadata metadata` + + User-provided metadata key-value pairs + + - `String name` + + Human-readable name for the environment + + - `JsonValue; type "environment"constant` + + The type of object (always 'environment') + + - `ENVIRONMENT("environment")` + + - `String updatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.environments.BetaEnvironment; +import com.anthropic.models.beta.environments.EnvironmentArchiveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaEnvironment betaEnvironment = client.beta().environments().archive("env_011CZkZ9X2dpNyB7HsEFoRfW"); + } +} +``` + +## Domain Types + +### Beta Cloud Config + +- `class BetaCloudConfig:` + + `cloud` environment configuration. + + - `Networking networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `BetaPackages packages` + + Package manager configuration. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + +### Beta Cloud Config Params + +- `class BetaCloudConfigParams:` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + + - `Optional networking` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetworkParams:` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `Optional allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `Optional allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `Optional> allowedHosts` + + Specifies domains the container can reach. + + - `Optional packages` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `Optional> apt` + + Ubuntu/Debian packages to install + + - `Optional> cargo` + + Rust packages to install + + - `Optional> gem` + + Ruby packages to install + + - `Optional> go` + + Go packages to install + + - `Optional> npm` + + Node.js packages to install + + - `Optional> pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + +### Beta Environment + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `String id` + + Environment identifier (e.g., 'env_...') + + - `Optional archivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `BetaCloudConfig config` + + `cloud` environment configuration. + + - `Networking networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `BetaPackages packages` + + Package manager configuration. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + + - `String createdAt` + + RFC 3339 timestamp when environment was created + + - `String description` + + User-provided description for the environment + + - `Metadata metadata` + + User-provided metadata key-value pairs + + - `String name` + + Human-readable name for the environment + + - `JsonValue; type "environment"constant` + + The type of object (always 'environment') + + - `ENVIRONMENT("environment")` + + - `String updatedAt` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `class BetaEnvironmentDeleteResponse:` + + Response after deleting an environment. + + - `String id` + + Environment identifier + + - `JsonValue; type "environment_deleted"constant` + + The type of response + + - `ENVIRONMENT_DELETED("environment_deleted")` + +### Beta Limited Network + +- `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + +### Beta Limited Network Params + +- `class BetaLimitedNetworkParams:` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `Optional allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `Optional allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `Optional> allowedHosts` + + Specifies domains the container can reach. + +### Beta Packages + +- `class BetaPackages:` + + Packages (and their versions) available in this environment. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + +### Beta Packages Params + +- `class BetaPackagesParams:` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `Optional> apt` + + Ubuntu/Debian packages to install + + - `Optional> cargo` + + Rust packages to install + + - `Optional> gem` + + Ruby packages to install + + - `Optional> go` + + Go packages to install + + - `Optional> npm` + + Node.js packages to install + + - `Optional> pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + +### Beta Unrestricted Network + +- `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` diff --git a/content/en/api/java/beta/environments/archive.md b/content/en/api/java/beta/environments/archive.md new file mode 100644 index 000000000..9ff8399ad --- /dev/null +++ b/content/en/api/java/beta/environments/archive.md @@ -0,0 +1,200 @@ +## Archive + +`BetaEnvironment beta().environments().archive(EnvironmentArchiveParamsparams = EnvironmentArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `EnvironmentArchiveParams params` + + - `Optional environmentId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `String id` + + Environment identifier (e.g., 'env_...') + + - `Optional archivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `BetaCloudConfig config` + + `cloud` environment configuration. + + - `Networking networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `BetaPackages packages` + + Package manager configuration. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + + - `String createdAt` + + RFC 3339 timestamp when environment was created + + - `String description` + + User-provided description for the environment + + - `Metadata metadata` + + User-provided metadata key-value pairs + + - `String name` + + Human-readable name for the environment + + - `JsonValue; type "environment"constant` + + The type of object (always 'environment') + + - `ENVIRONMENT("environment")` + + - `String updatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.environments.BetaEnvironment; +import com.anthropic.models.beta.environments.EnvironmentArchiveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaEnvironment betaEnvironment = client.beta().environments().archive("env_011CZkZ9X2dpNyB7HsEFoRfW"); + } +} +``` diff --git a/content/en/api/java/beta/environments/create.md b/content/en/api/java/beta/environments/create.md new file mode 100644 index 000000000..556f8571d --- /dev/null +++ b/content/en/api/java/beta/environments/create.md @@ -0,0 +1,220 @@ +## Create + +`BetaEnvironment beta().environments().create(EnvironmentCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `EnvironmentCreateParams params` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `String name` + + Human-readable name for the environment + + - `Optional config` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Optional description` + + Optional description of the environment + + - `Optional metadata` + + User-provided metadata key-value pairs + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `String id` + + Environment identifier (e.g., 'env_...') + + - `Optional archivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `BetaCloudConfig config` + + `cloud` environment configuration. + + - `Networking networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `BetaPackages packages` + + Package manager configuration. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + + - `String createdAt` + + RFC 3339 timestamp when environment was created + + - `String description` + + User-provided description for the environment + + - `Metadata metadata` + + User-provided metadata key-value pairs + + - `String name` + + Human-readable name for the environment + + - `JsonValue; type "environment"constant` + + The type of object (always 'environment') + + - `ENVIRONMENT("environment")` + + - `String updatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.environments.BetaEnvironment; +import com.anthropic.models.beta.environments.EnvironmentCreateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + EnvironmentCreateParams params = EnvironmentCreateParams.builder() + .name("python-data-analysis") + .build(); + BetaEnvironment betaEnvironment = client.beta().environments().create(params); + } +} +``` diff --git a/content/en/api/java/beta/environments/delete.md b/content/en/api/java/beta/environments/delete.md new file mode 100644 index 000000000..b1aa151e1 --- /dev/null +++ b/content/en/api/java/beta/environments/delete.md @@ -0,0 +1,96 @@ +## Delete + +`BetaEnvironmentDeleteResponse beta().environments().delete(EnvironmentDeleteParamsparams = EnvironmentDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `EnvironmentDeleteParams params` + + - `Optional environmentId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaEnvironmentDeleteResponse:` + + Response after deleting an environment. + + - `String id` + + Environment identifier + + - `JsonValue; type "environment_deleted"constant` + + The type of response + + - `ENVIRONMENT_DELETED("environment_deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.environments.BetaEnvironmentDeleteResponse; +import com.anthropic.models.beta.environments.EnvironmentDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaEnvironmentDeleteResponse betaEnvironmentDeleteResponse = client.beta().environments().delete("env_011CZkZ9X2dpNyB7HsEFoRfW"); + } +} +``` diff --git a/content/en/api/java/beta/environments/list.md b/content/en/api/java/beta/environments/list.md new file mode 100644 index 000000000..b966ced84 --- /dev/null +++ b/content/en/api/java/beta/environments/list.md @@ -0,0 +1,210 @@ +## List + +`EnvironmentListPage beta().environments().list(EnvironmentListParamsparams = EnvironmentListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `EnvironmentListParams params` + + - `Optional includeArchived` + + Include archived environments in the response + + - `Optional limit` + + Maximum number of environments to return + + - `Optional page` + + Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `String id` + + Environment identifier (e.g., 'env_...') + + - `Optional archivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `BetaCloudConfig config` + + `cloud` environment configuration. + + - `Networking networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `BetaPackages packages` + + Package manager configuration. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + + - `String createdAt` + + RFC 3339 timestamp when environment was created + + - `String description` + + User-provided description for the environment + + - `Metadata metadata` + + User-provided metadata key-value pairs + + - `String name` + + Human-readable name for the environment + + - `JsonValue; type "environment"constant` + + The type of object (always 'environment') + + - `ENVIRONMENT("environment")` + + - `String updatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.environments.EnvironmentListPage; +import com.anthropic.models.beta.environments.EnvironmentListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + EnvironmentListPage page = client.beta().environments().list(); + } +} +``` diff --git a/content/en/api/java/beta/environments/retrieve.md b/content/en/api/java/beta/environments/retrieve.md new file mode 100644 index 000000000..54f17f1c1 --- /dev/null +++ b/content/en/api/java/beta/environments/retrieve.md @@ -0,0 +1,200 @@ +## Retrieve + +`BetaEnvironment beta().environments().retrieve(EnvironmentRetrieveParamsparams = EnvironmentRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `EnvironmentRetrieveParams params` + + - `Optional environmentId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `String id` + + Environment identifier (e.g., 'env_...') + + - `Optional archivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `BetaCloudConfig config` + + `cloud` environment configuration. + + - `Networking networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `BetaPackages packages` + + Package manager configuration. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + + - `String createdAt` + + RFC 3339 timestamp when environment was created + + - `String description` + + User-provided description for the environment + + - `Metadata metadata` + + User-provided metadata key-value pairs + + - `String name` + + Human-readable name for the environment + + - `JsonValue; type "environment"constant` + + The type of object (always 'environment') + + - `ENVIRONMENT("environment")` + + - `String updatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.environments.BetaEnvironment; +import com.anthropic.models.beta.environments.EnvironmentRetrieveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaEnvironment betaEnvironment = client.beta().environments().retrieve("env_011CZkZ9X2dpNyB7HsEFoRfW"); + } +} +``` diff --git a/content/en/api/java/beta/environments/update.md b/content/en/api/java/beta/environments/update.md new file mode 100644 index 000000000..a857919fc --- /dev/null +++ b/content/en/api/java/beta/environments/update.md @@ -0,0 +1,219 @@ +## Update + +`BetaEnvironment beta().environments().update(EnvironmentUpdateParamsparams = EnvironmentUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `EnvironmentUpdateParams params` + + - `Optional environmentId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Optional config` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `Optional description` + + Updated description of the environment + + - `Optional metadata` + + User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + + - `Optional name` + + Updated name for the environment + +### Returns + +- `class BetaEnvironment:` + + Unified Environment resource for both cloud and BYOC environments. + + - `String id` + + Environment identifier (e.g., 'env_...') + + - `Optional archivedAt` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `BetaCloudConfig config` + + `cloud` environment configuration. + + - `Networking networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork:` + + Unrestricted network access. + + - `JsonValue; type "unrestricted"constant` + + Network policy type + + - `UNRESTRICTED("unrestricted")` + + - `class BetaLimitedNetwork:` + + Limited network access. + + - `boolean allowMcpServers` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `boolean allowPackageManagers` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `List allowedHosts` + + Specifies domains the container can reach. + + - `JsonValue; type "limited"constant` + + Network policy type + + - `LIMITED("limited")` + + - `BetaPackages packages` + + Package manager configuration. + + - `List apt` + + Ubuntu/Debian packages to install + + - `List cargo` + + Rust packages to install + + - `List gem` + + Ruby packages to install + + - `List go` + + Go packages to install + + - `List npm` + + Node.js packages to install + + - `List pip` + + Python packages to install + + - `Optional type` + + Package configuration type + + - `PACKAGES("packages")` + + - `JsonValue; type "cloud"constant` + + Environment type + + - `CLOUD("cloud")` + + - `String createdAt` + + RFC 3339 timestamp when environment was created + + - `String description` + + User-provided description for the environment + + - `Metadata metadata` + + User-provided metadata key-value pairs + + - `String name` + + Human-readable name for the environment + + - `JsonValue; type "environment"constant` + + The type of object (always 'environment') + + - `ENVIRONMENT("environment")` + + - `String updatedAt` + + RFC 3339 timestamp when environment was last updated + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.environments.BetaEnvironment; +import com.anthropic.models.beta.environments.EnvironmentUpdateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaEnvironment betaEnvironment = client.beta().environments().update("env_011CZkZ9X2dpNyB7HsEFoRfW"); + } +} +``` diff --git a/content/en/api/java/beta/files.md b/content/en/api/java/beta/files.md index 2095aef2a..c978e0660 100644 --- a/content/en/api/java/beta/files.md +++ b/content/en/api/java/beta/files.md @@ -58,8 +58,6 @@ Upload File - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `String file` The file to upload @@ -102,6 +100,20 @@ Upload File Whether the file can be downloaded. + - `Optional scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `String id` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonValue; type "session"constant` + + The type of scope (e.g., `"session"`). + + - `SESSION("session")` + ### Example ```java @@ -153,6 +165,10 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. + - `Optional scopeId` + + Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `Optional> betas` Optional header to specify the beta version(s) you want to use. @@ -199,8 +215,6 @@ List Files - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class FileMetadata:` @@ -239,6 +253,20 @@ List Files Whether the file can be downloaded. + - `Optional scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `String id` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonValue; type "session"constant` + + The type of scope (e.g., `"session"`). + + - `SESSION("session")` + ### Example ```java @@ -322,8 +350,6 @@ Download File - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Example ```java @@ -407,8 +433,6 @@ Get File Metadata - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class FileMetadata:` @@ -447,6 +471,20 @@ Get File Metadata Whether the file can be downloaded. + - `Optional scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `String id` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonValue; type "session"constant` + + The type of scope (e.g., `"session"`). + + - `SESSION("session")` + ### Example ```java @@ -530,8 +568,6 @@ Delete File - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class DeletedFile:` @@ -571,6 +607,20 @@ public final class Main { ## Domain Types +### Beta File Scope + +- `class BetaFileScope:` + + - `String id` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonValue; type "session"constant` + + The type of scope (e.g., `"session"`). + + - `SESSION("session")` + ### Deleted File - `class DeletedFile:` @@ -624,3 +674,17 @@ public final class Main { - `Optional downloadable` Whether the file can be downloaded. + + - `Optional scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `String id` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonValue; type "session"constant` + + The type of scope (e.g., `"session"`). + + - `SESSION("session")` diff --git a/content/en/api/java/beta/files/delete.md b/content/en/api/java/beta/files/delete.md index c9243603b..646c1a038 100644 --- a/content/en/api/java/beta/files/delete.md +++ b/content/en/api/java/beta/files/delete.md @@ -60,8 +60,6 @@ Delete File - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class DeletedFile:` diff --git a/content/en/api/java/beta/files/download.md b/content/en/api/java/beta/files/download.md index 297868e59..579a40707 100644 --- a/content/en/api/java/beta/files/download.md +++ b/content/en/api/java/beta/files/download.md @@ -60,8 +60,6 @@ Download File - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Example ```java diff --git a/content/en/api/java/beta/files/list.md b/content/en/api/java/beta/files/list.md index 1af8c1548..6a514b0bc 100644 --- a/content/en/api/java/beta/files/list.md +++ b/content/en/api/java/beta/files/list.md @@ -24,6 +24,10 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. + - `Optional scopeId` + + Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `Optional> betas` Optional header to specify the beta version(s) you want to use. @@ -70,8 +74,6 @@ List Files - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class FileMetadata:` @@ -110,6 +112,20 @@ List Files Whether the file can be downloaded. + - `Optional scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `String id` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonValue; type "session"constant` + + The type of scope (e.g., `"session"`). + + - `SESSION("session")` + ### Example ```java diff --git a/content/en/api/java/beta/files/retrieve_metadata.md b/content/en/api/java/beta/files/retrieve_metadata.md index 1571dd4dc..ce21ac088 100644 --- a/content/en/api/java/beta/files/retrieve_metadata.md +++ b/content/en/api/java/beta/files/retrieve_metadata.md @@ -60,8 +60,6 @@ Get File Metadata - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class FileMetadata:` @@ -100,6 +98,20 @@ Get File Metadata Whether the file can be downloaded. + - `Optional scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `String id` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonValue; type "session"constant` + + The type of scope (e.g., `"session"`). + + - `SESSION("session")` + ### Example ```java diff --git a/content/en/api/java/beta/files/upload.md b/content/en/api/java/beta/files/upload.md index ab1fc2461..d7f6ab166 100644 --- a/content/en/api/java/beta/files/upload.md +++ b/content/en/api/java/beta/files/upload.md @@ -56,8 +56,6 @@ Upload File - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `String file` The file to upload @@ -100,6 +98,20 @@ Upload File Whether the file can be downloaded. + - `Optional scope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `String id` + + The ID of the scoping resource (e.g., the session ID). + + - `JsonValue; type "session"constant` + + The type of scope (e.g., `"session"`). + + - `SESSION("session")` + ### Example ```java diff --git a/content/en/api/java/beta/messages.md b/content/en/api/java/beta/messages.md index 3d48ad2db..17c03194a 100644 --- a/content/en/api/java/beta/messages.md +++ b/content/en/api/java/beta/messages.md @@ -62,8 +62,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `long maxTokens` The maximum number of tokens to generate before stopping. @@ -4383,10 +4381,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. - - `Optional userProfileId` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - ### Returns - `class BetaMessage:` @@ -5310,9 +5304,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -5696,8 +5694,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `List messages` Input messages. @@ -17064,9 +17060,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -22400,9 +22400,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -23636,9 +23640,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -32215,8 +32223,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `List requests` List of requests for prompt completion. Each is an individual request to create a Message. @@ -34818,9 +34824,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -36887,10 +36897,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `Optional userProfileId` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - ### Returns - `class BetaMessageBatch:` @@ -37077,8 +37083,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaMessageBatch:` @@ -37264,8 +37268,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaMessageBatch:` @@ -37443,8 +37445,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaMessageBatch:` @@ -37622,8 +37622,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaDeletedMessageBatch:` @@ -37727,8 +37725,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaMessageBatchIndividualResponse:` @@ -38670,9 +38666,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -40248,9 +40248,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -41612,9 +41616,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -42938,9 +42946,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` diff --git a/content/en/api/java/beta/messages/batches.md b/content/en/api/java/beta/messages/batches.md index b740b9435..d63f91abd 100644 --- a/content/en/api/java/beta/messages/batches.md +++ b/content/en/api/java/beta/messages/batches.md @@ -62,8 +62,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `List requests` List of requests for prompt completion. Each is an individual request to create a Message. @@ -2665,9 +2663,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -4734,10 +4736,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `Optional userProfileId` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - ### Returns - `class BetaMessageBatch:` @@ -4924,8 +4922,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaMessageBatch:` @@ -5111,8 +5107,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaMessageBatch:` @@ -5290,8 +5284,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaMessageBatch:` @@ -5469,8 +5461,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaDeletedMessageBatch:` @@ -5574,8 +5564,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaMessageBatchIndividualResponse:` @@ -6517,9 +6505,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -8095,9 +8087,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -9459,9 +9455,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -10785,9 +10785,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` diff --git a/content/en/api/java/beta/messages/batches/cancel.md b/content/en/api/java/beta/messages/batches/cancel.md index ec363bede..1b607e6e4 100644 --- a/content/en/api/java/beta/messages/batches/cancel.md +++ b/content/en/api/java/beta/messages/batches/cancel.md @@ -64,8 +64,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaMessageBatch:` diff --git a/content/en/api/java/beta/messages/batches/create.md b/content/en/api/java/beta/messages/batches/create.md index 100ea7d26..c8663745d 100644 --- a/content/en/api/java/beta/messages/batches/create.md +++ b/content/en/api/java/beta/messages/batches/create.md @@ -60,8 +60,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `List requests` List of requests for prompt completion. Each is an individual request to create a Message. @@ -2663,9 +2661,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -4732,10 +4734,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `Optional userProfileId` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - ### Returns - `class BetaMessageBatch:` diff --git a/content/en/api/java/beta/messages/batches/delete.md b/content/en/api/java/beta/messages/batches/delete.md index cd99d4b22..13cddf7f8 100644 --- a/content/en/api/java/beta/messages/batches/delete.md +++ b/content/en/api/java/beta/messages/batches/delete.md @@ -64,8 +64,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaDeletedMessageBatch:` diff --git a/content/en/api/java/beta/messages/batches/list.md b/content/en/api/java/beta/messages/batches/list.md index 5401a87bf..3ed88581d 100644 --- a/content/en/api/java/beta/messages/batches/list.md +++ b/content/en/api/java/beta/messages/batches/list.md @@ -72,8 +72,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaMessageBatch:` diff --git a/content/en/api/java/beta/messages/batches/results.md b/content/en/api/java/beta/messages/batches/results.md index b9c88de2f..114845086 100644 --- a/content/en/api/java/beta/messages/batches/results.md +++ b/content/en/api/java/beta/messages/batches/results.md @@ -64,8 +64,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaMessageBatchIndividualResponse:` @@ -1007,9 +1005,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` diff --git a/content/en/api/java/beta/messages/batches/retrieve.md b/content/en/api/java/beta/messages/batches/retrieve.md index bb4b2b5c7..70f5f10d6 100644 --- a/content/en/api/java/beta/messages/batches/retrieve.md +++ b/content/en/api/java/beta/messages/batches/retrieve.md @@ -62,8 +62,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaMessageBatch:` diff --git a/content/en/api/java/beta/messages/count_tokens.md b/content/en/api/java/beta/messages/count_tokens.md index 7c9750a5a..4733632fb 100644 --- a/content/en/api/java/beta/messages/count_tokens.md +++ b/content/en/api/java/beta/messages/count_tokens.md @@ -60,8 +60,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `List messages` Input messages. diff --git a/content/en/api/java/beta/messages/create.md b/content/en/api/java/beta/messages/create.md index 1612fdc4c..b19957602 100644 --- a/content/en/api/java/beta/messages/create.md +++ b/content/en/api/java/beta/messages/create.md @@ -60,8 +60,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `long maxTokens` The maximum number of tokens to generate before stopping. @@ -4381,10 +4379,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. - - `Optional userProfileId` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - ### Returns - `class BetaMessage:` @@ -5308,9 +5302,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` diff --git a/content/en/api/java/beta/models.md b/content/en/api/java/beta/models.md index 78ad71410..8c48829f8 100644 --- a/content/en/api/java/beta/models.md +++ b/content/en/api/java/beta/models.md @@ -74,8 +74,6 @@ The Models API response can be used to determine which models are available for - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaModelInfo:` @@ -345,8 +343,6 @@ The Models API response can be used to determine information about a specific mo - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaModelInfo:` diff --git a/content/en/api/java/beta/models/list.md b/content/en/api/java/beta/models/list.md index 537fdcb7a..fec35f078 100644 --- a/content/en/api/java/beta/models/list.md +++ b/content/en/api/java/beta/models/list.md @@ -72,8 +72,6 @@ The Models API response can be used to determine which models are available for - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaModelInfo:` diff --git a/content/en/api/java/beta/models/retrieve.md b/content/en/api/java/beta/models/retrieve.md index 3943adfe2..7297cbe97 100644 --- a/content/en/api/java/beta/models/retrieve.md +++ b/content/en/api/java/beta/models/retrieve.md @@ -62,8 +62,6 @@ The Models API response can be used to determine information about a specific mo - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class BetaModelInfo:` diff --git a/content/en/api/java/beta/sessions.md b/content/en/api/java/beta/sessions.md new file mode 100644 index 000000000..d31e6a986 --- /dev/null +++ b/content/en/api/java/beta/sessions.md @@ -0,0 +1,14129 @@ +# Sessions + +## Create + +`BetaManagedAgentsSession beta().sessions().create(SessionCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `SessionCreateParams params` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Agent agent` + + Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `String` + + - `class BetaManagedAgentsAgentParams:` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `String id` + + The `agent` ID. + + - `Type type` + + - `AGENT("agent")` + + - `Optional version` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + + - `String environmentId` + + ID of the `environment` defining the container configuration for this session. + + - `Optional metadata` + + Arbitrary key-value metadata attached to the session. + + - `Optional> resources` + + Resources (e.g. repositories, files) to mount into the session's container. + + - `class BetaManagedAgentsGitHubRepositoryResourceParams:` + + Mount a GitHub repository into the session's container. + + - `String authorizationToken` + + GitHub authorization token used to clone the repository. + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `String url` + + Github URL of the repository + + - `Optional checkout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `Optional mountPath` + + Mount path in the container. Defaults to `/workspace/`. + + - `class BetaManagedAgentsFileResourceParams:` + + Mount a file uploaded via the Files API into the session. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Optional mountPath` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `Optional title` + + Human-readable session title. + + - `Optional> vaultIds` + + Vault IDs for stored credentials the agent can use during the session. + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `String id` + + - `BetaManagedAgentsSessionAgent agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `String id` + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `long version` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String environmentId` + + - `Metadata metadata` + + - `List resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionStats stats` + + Timing statistics for a session. + + - `Optional activeSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Optional durationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status status` + + SessionStatus enum + + - `RESCHEDULING("rescheduling")` + + - `RUNNING("running")` + + - `IDLE("idle")` + + - `TERMINATED("terminated")` + + - `Optional title` + + - `Type type` + + - `SESSION("session")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionUsage usage` + + Cumulative token usage for a session across all turns. + + - `Optional cacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Optional cacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Optional inputTokens` + + Total input tokens consumed across all turns. + + - `Optional outputTokens` + + Total output tokens generated across all turns. + + - `List vaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsSession; +import com.anthropic.models.beta.sessions.SessionCreateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + SessionCreateParams params = SessionCreateParams.builder() + .agent("agent_011CZkYpogX7uDKUyvBTophP") + .environmentId("env_011CZkZ9X2dpNyB7HsEFoRfW") + .build(); + BetaManagedAgentsSession betaManagedAgentsSession = client.beta().sessions().create(params); + } +} +``` + +## List + +`SessionListPage beta().sessions().list(SessionListParamsparams = SessionListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `SessionListParams params` + + - `Optional agentId` + + Filter sessions created with this agent ID. + + - `Optional agentVersion` + + Filter by agent version. Only applies when agent_id is also set. + + - `Optional createdAtGt` + + Return sessions created after this time (exclusive). + + - `Optional createdAtGte` + + Return sessions created at or after this time (inclusive). + + - `Optional createdAtLt` + + Return sessions created before this time (exclusive). + + - `Optional createdAtLte` + + Return sessions created at or before this time (inclusive). + + - `Optional includeArchived` + + When true, includes archived sessions. Default: false (exclude archived). + + - `Optional limit` + + Maximum number of results to return. + + - `Optional order` + + Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `ASC("asc")` + + - `DESC("desc")` + + - `Optional page` + + Opaque pagination cursor from a previous response's next_page. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `String id` + + - `BetaManagedAgentsSessionAgent agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `String id` + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `long version` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String environmentId` + + - `Metadata metadata` + + - `List resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionStats stats` + + Timing statistics for a session. + + - `Optional activeSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Optional durationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status status` + + SessionStatus enum + + - `RESCHEDULING("rescheduling")` + + - `RUNNING("running")` + + - `IDLE("idle")` + + - `TERMINATED("terminated")` + + - `Optional title` + + - `Type type` + + - `SESSION("session")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionUsage usage` + + Cumulative token usage for a session across all turns. + + - `Optional cacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Optional cacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Optional inputTokens` + + Total input tokens consumed across all turns. + + - `Optional outputTokens` + + Total output tokens generated across all turns. + + - `List vaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.SessionListPage; +import com.anthropic.models.beta.sessions.SessionListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + SessionListPage page = client.beta().sessions().list(); + } +} +``` + +## Retrieve + +`BetaManagedAgentsSession beta().sessions().retrieve(SessionRetrieveParamsparams = SessionRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `SessionRetrieveParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `String id` + + - `BetaManagedAgentsSessionAgent agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `String id` + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `long version` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String environmentId` + + - `Metadata metadata` + + - `List resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionStats stats` + + Timing statistics for a session. + + - `Optional activeSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Optional durationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status status` + + SessionStatus enum + + - `RESCHEDULING("rescheduling")` + + - `RUNNING("running")` + + - `IDLE("idle")` + + - `TERMINATED("terminated")` + + - `Optional title` + + - `Type type` + + - `SESSION("session")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionUsage usage` + + Cumulative token usage for a session across all turns. + + - `Optional cacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Optional cacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Optional inputTokens` + + Total input tokens consumed across all turns. + + - `Optional outputTokens` + + Total output tokens generated across all turns. + + - `List vaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsSession; +import com.anthropic.models.beta.sessions.SessionRetrieveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsSession betaManagedAgentsSession = client.beta().sessions().retrieve("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` + +## Update + +`BetaManagedAgentsSession beta().sessions().update(SessionUpdateParamsparams = SessionUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `SessionUpdateParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Optional metadata` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + + - `Optional title` + + Human-readable session title. + + - `Optional> vaultIds` + + Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `String id` + + - `BetaManagedAgentsSessionAgent agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `String id` + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `long version` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String environmentId` + + - `Metadata metadata` + + - `List resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionStats stats` + + Timing statistics for a session. + + - `Optional activeSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Optional durationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status status` + + SessionStatus enum + + - `RESCHEDULING("rescheduling")` + + - `RUNNING("running")` + + - `IDLE("idle")` + + - `TERMINATED("terminated")` + + - `Optional title` + + - `Type type` + + - `SESSION("session")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionUsage usage` + + Cumulative token usage for a session across all turns. + + - `Optional cacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Optional cacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Optional inputTokens` + + Total input tokens consumed across all turns. + + - `Optional outputTokens` + + Total output tokens generated across all turns. + + - `List vaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsSession; +import com.anthropic.models.beta.sessions.SessionUpdateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsSession betaManagedAgentsSession = client.beta().sessions().update("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` + +## Delete + +`BetaManagedAgentsDeletedSession beta().sessions().delete(SessionDeleteParamsparams = SessionDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `SessionDeleteParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsDeletedSession:` + + Confirmation that a `session` has been permanently deleted. + + - `String id` + + - `Type type` + + - `SESSION_DELETED("session_deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsDeletedSession; +import com.anthropic.models.beta.sessions.SessionDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsDeletedSession betaManagedAgentsDeletedSession = client.beta().sessions().delete("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` + +## Archive + +`BetaManagedAgentsSession beta().sessions().archive(SessionArchiveParamsparams = SessionArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `SessionArchiveParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `String id` + + - `BetaManagedAgentsSessionAgent agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `String id` + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `long version` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String environmentId` + + - `Metadata metadata` + + - `List resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionStats stats` + + Timing statistics for a session. + + - `Optional activeSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Optional durationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status status` + + SessionStatus enum + + - `RESCHEDULING("rescheduling")` + + - `RUNNING("running")` + + - `IDLE("idle")` + + - `TERMINATED("terminated")` + + - `Optional title` + + - `Type type` + + - `SESSION("session")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionUsage usage` + + Cumulative token usage for a session across all turns. + + - `Optional cacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Optional cacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Optional inputTokens` + + Total input tokens consumed across all turns. + + - `Optional outputTokens` + + Total output tokens generated across all turns. + + - `List vaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsSession; +import com.anthropic.models.beta.sessions.SessionArchiveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsSession betaManagedAgentsSession = client.beta().sessions().archive("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `class BetaManagedAgentsAgentParams:` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `String id` + + The `agent` ID. + + - `Type type` + + - `AGENT("agent")` + + - `Optional version` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + +### Beta Managed Agents Cache Creation Usage + +- `class BetaManagedAgentsCacheCreationUsage:` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + +### Beta Managed Agents Deleted Session + +- `class BetaManagedAgentsDeletedSession:` + + Confirmation that a `session` has been permanently deleted. + + - `String id` + + - `Type type` + + - `SESSION_DELETED("session_deleted")` + +### Beta Managed Agents File Resource Params + +- `class BetaManagedAgentsFileResourceParams:` + + Mount a file uploaded via the Files API into the session. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Optional mountPath` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `class BetaManagedAgentsGitHubRepositoryResourceParams:` + + Mount a GitHub repository into the session's container. + + - `String authorizationToken` + + GitHub authorization token used to clone the repository. + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `String url` + + Github URL of the repository + + - `Optional checkout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `Optional mountPath` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `String id` + + - `BetaManagedAgentsSessionAgent agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `String id` + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `long version` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String environmentId` + + - `Metadata metadata` + + - `List resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionStats stats` + + Timing statistics for a session. + + - `Optional activeSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Optional durationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status status` + + SessionStatus enum + + - `RESCHEDULING("rescheduling")` + + - `RUNNING("running")` + + - `IDLE("idle")` + + - `TERMINATED("terminated")` + + - `Optional title` + + - `Type type` + + - `SESSION("session")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionUsage usage` + + Cumulative token usage for a session across all turns. + + - `Optional cacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Optional cacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Optional inputTokens` + + Total input tokens consumed across all turns. + + - `Optional outputTokens` + + Total output tokens generated across all turns. + + - `List vaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `class BetaManagedAgentsSessionAgent:` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `String id` + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `long version` + +### Beta Managed Agents Session Stats + +- `class BetaManagedAgentsSessionStats:` + + Timing statistics for a session. + + - `Optional activeSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Optional durationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `class BetaManagedAgentsSessionUsage:` + + Cumulative token usage for a session across all turns. + + - `Optional cacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Optional cacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Optional inputTokens` + + Total input tokens consumed across all turns. + + - `Optional outputTokens` + + Total output tokens generated across all turns. + +# Events + +## List + +`EventListPage beta().sessions().events().list(EventListParamsparams = EventListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `EventListParams params` + + - `Optional sessionId` + + - `Optional limit` + + Query parameter for limit + + - `Optional order` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `ASC("asc")` + + - `DESC("desc")` + + - `Optional page` + + Opaque pagination cursor from a previous response's next_page. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsSessionEvent: A class that can be one of several variants.union` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the custom tool being called. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of text blocks comprising the agent response. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MESSAGE("agent.message")` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THINKING("agent.thinking")` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String mcpServerName` + + Name of the MCP server providing the tool. + + - `String name` + + Name of the MCP tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `String id` + + Unique identifier for this event. + + - `String mcpToolUseId` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the agent tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_TOOL_USE("agent.tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `String toolUseId` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type type` + + - `AGENT_TOOL_RESULT("agent.tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `String id` + + Unique identifier for this event. + + - `Error error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_ERROR("session.error")` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RUNNING("session.status_running")` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `StopReason stopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + + - `Type type` + + - `SESSION_STATUS_IDLE("session.status_idle")` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_TERMINATED("session.status_terminated")` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_START("span.model_request_start")` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `String id` + + Unique identifier for this event. + + - `Optional isError` + + Whether the model request resulted in an error. + + - `String modelRequestStartId` + + The id of the corresponding `span.model_request_start` event. + + - `BetaManagedAgentsSpanModelUsage modelUsage` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_END("span.model_request_end")` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_DELETED("session.deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.events.EventListPage; +import com.anthropic.models.beta.sessions.events.EventListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + EventListPage page = client.beta().sessions().events().list("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` + +## Send + +`BetaManagedAgentsSendSessionEvents beta().sessions().events().send(EventSendParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `EventSendParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `List events` + + Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `List content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + +### Returns + +- `class BetaManagedAgentsSendSessionEvents:` + + Events that were successfully sent to the session. + + - `Optional> data` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsSendSessionEvents; +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsTextBlock; +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams; +import com.anthropic.models.beta.sessions.events.EventSendParams; +import java.util.List; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + EventSendParams params = EventSendParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .addUserMessageEvent(List.of(BetaManagedAgentsUserMessageEventParams.Content.ofText(BetaManagedAgentsTextBlock.builder() + .text("Where is my order #1234?") + .type(BetaManagedAgentsTextBlock.Type.TEXT) + .build()))) + .build(); + BetaManagedAgentsSendSessionEvents betaManagedAgentsSendSessionEvents = client.beta().sessions().events().send(params); + } +} +``` + +## Stream + +`BetaManagedAgentsStreamSessionEvents beta().sessions().events().streamStreaming(EventStreamParamsparams = EventStreamParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `EventStreamParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the custom tool being called. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of text blocks comprising the agent response. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MESSAGE("agent.message")` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THINKING("agent.thinking")` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String mcpServerName` + + Name of the MCP server providing the tool. + + - `String name` + + Name of the MCP tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `String id` + + Unique identifier for this event. + + - `String mcpToolUseId` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the agent tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_TOOL_USE("agent.tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `String toolUseId` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type type` + + - `AGENT_TOOL_RESULT("agent.tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `String id` + + Unique identifier for this event. + + - `Error error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_ERROR("session.error")` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RUNNING("session.status_running")` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `StopReason stopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + + - `Type type` + + - `SESSION_STATUS_IDLE("session.status_idle")` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_TERMINATED("session.status_terminated")` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_START("span.model_request_start")` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `String id` + + Unique identifier for this event. + + - `Optional isError` + + Whether the model request resulted in an error. + + - `String modelRequestStartId` + + The id of the corresponding `span.model_request_start` event. + + - `BetaManagedAgentsSpanModelUsage modelUsage` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_END("span.model_request_end")` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_DELETED("session.deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.core.http.StreamResponse; +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsStreamSessionEvents; +import com.anthropic.models.beta.sessions.events.EventStreamParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + StreamResponse betaManagedAgentsStreamSessionEvents = client.beta().sessions().events().streamStreaming("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the custom tool being called. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `String id` + + Unique identifier for this event. + + - `String mcpToolUseId` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String mcpServerName` + + Name of the MCP server providing the tool. + + - `String name` + + Name of the MCP tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + +### Beta Managed Agents Agent Message Event + +- `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of text blocks comprising the agent response. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MESSAGE("agent.message")` + +### Beta Managed Agents Agent Thinking Event + +- `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THINKING("agent.thinking")` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")` + +### Beta Managed Agents Agent Tool Result Event + +- `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `String toolUseId` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type type` + + - `AGENT_TOOL_RESULT("agent.tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the agent tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_TOOL_USE("agent.tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + +### Beta Managed Agents Base64 Document Source + +- `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + +### Beta Managed Agents Base64 Image Source + +- `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + +### Beta Managed Agents Billing Error + +- `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + +### Beta Managed Agents Document Block + +- `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + +### Beta Managed Agents Event Params + +- `class BetaManagedAgentsEventParams: A class that can be one of several variants.union` + + Union type for event parameters that can be sent to a session. + + - `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `List content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + +### Beta Managed Agents File Image Source + +- `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + +### Beta Managed Agents Image Block + +- `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + +### Beta Managed Agents MCP Authentication Failed Error + +- `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + +### Beta Managed Agents MCP Connection Failed Error + +- `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + +### Beta Managed Agents Model Overloaded Error + +- `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + +### Beta Managed Agents Model Rate Limited Error + +- `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + +### Beta Managed Agents Model Request Failed Error + +- `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + +### Beta Managed Agents Plain Text Document Source + +- `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + +### Beta Managed Agents Retry Status Exhausted + +- `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + +### Beta Managed Agents Retry Status Retrying + +- `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + +### Beta Managed Agents Retry Status Terminal + +- `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + +### Beta Managed Agents Send Session Events + +- `class BetaManagedAgentsSendSessionEvents:` + + Events that were successfully sent to the session. + + - `Optional> data` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_DELETED("session.deleted")` + +### Beta Managed Agents Session End Turn + +- `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + +### Beta Managed Agents Session Error Event + +- `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `String id` + + Unique identifier for this event. + + - `Error error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_ERROR("session.error")` + +### Beta Managed Agents Session Event + +- `class BetaManagedAgentsSessionEvent: A class that can be one of several variants.union` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the custom tool being called. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of text blocks comprising the agent response. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MESSAGE("agent.message")` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THINKING("agent.thinking")` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String mcpServerName` + + Name of the MCP server providing the tool. + + - `String name` + + Name of the MCP tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `String id` + + Unique identifier for this event. + + - `String mcpToolUseId` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the agent tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_TOOL_USE("agent.tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `String toolUseId` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type type` + + - `AGENT_TOOL_RESULT("agent.tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `String id` + + Unique identifier for this event. + + - `Error error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_ERROR("session.error")` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RUNNING("session.status_running")` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `StopReason stopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + + - `Type type` + + - `SESSION_STATUS_IDLE("session.status_idle")` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_TERMINATED("session.status_terminated")` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_START("span.model_request_start")` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `String id` + + Unique identifier for this event. + + - `Optional isError` + + Whether the model request resulted in an error. + + - `String modelRequestStartId` + + The id of the corresponding `span.model_request_start` event. + + - `BetaManagedAgentsSpanModelUsage modelUsage` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_END("span.model_request_end")` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_DELETED("session.deleted")` + +### Beta Managed Agents Session Requires Action + +- `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + +### Beta Managed Agents Session Retries Exhausted + +- `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + +### Beta Managed Agents Session Status Idle Event + +- `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `StopReason stopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + + - `Type type` + + - `SESSION_STATUS_IDLE("session.status_idle")` + +### Beta Managed Agents Session Status Rescheduled Event + +- `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")` + +### Beta Managed Agents Session Status Running Event + +- `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RUNNING("session.status_running")` + +### Beta Managed Agents Session Status Terminated Event + +- `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_TERMINATED("session.status_terminated")` + +### Beta Managed Agents Span Model Request End Event + +- `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `String id` + + Unique identifier for this event. + + - `Optional isError` + + Whether the model request resulted in an error. + + - `String modelRequestStartId` + + The id of the corresponding `span.model_request_start` event. + + - `BetaManagedAgentsSpanModelUsage modelUsage` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_END("span.model_request_end")` + +### Beta Managed Agents Span Model Request Start Event + +- `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_START("span.model_request_start")` + +### Beta Managed Agents Span Model Usage + +- `class BetaManagedAgentsSpanModelUsage:` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + +### Beta Managed Agents Stream Session Events + +- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the custom tool being called. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of text blocks comprising the agent response. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MESSAGE("agent.message")` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THINKING("agent.thinking")` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String mcpServerName` + + Name of the MCP server providing the tool. + + - `String name` + + Name of the MCP tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `String id` + + Unique identifier for this event. + + - `String mcpToolUseId` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the agent tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_TOOL_USE("agent.tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `String toolUseId` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type type` + + - `AGENT_TOOL_RESULT("agent.tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `String id` + + Unique identifier for this event. + + - `Error error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_ERROR("session.error")` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RUNNING("session.status_running")` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `StopReason stopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + + - `Type type` + + - `SESSION_STATUS_IDLE("session.status_idle")` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_TERMINATED("session.status_terminated")` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_START("span.model_request_start")` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `String id` + + Unique identifier for this event. + + - `Optional isError` + + Whether the model request resulted in an error. + + - `String modelRequestStartId` + + The id of the corresponding `span.model_request_start` event. + + - `BetaManagedAgentsSpanModelUsage modelUsage` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_END("span.model_request_end")` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_DELETED("session.deleted")` + +### Beta Managed Agents Text Block + +- `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + +### Beta Managed Agents Unknown Error + +- `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + +### Beta Managed Agents URL Document Source + +- `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + +### Beta Managed Agents User Message Event + +- `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `List content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + +### Beta Managed Agents User Tool Confirmation Event + +- `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`BetaManagedAgentsFileResource beta().sessions().resources().add(ResourceAddParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `ResourceAddParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `BetaManagedAgentsFileResourceParams betaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + +### Returns + +- `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsFileResourceParams; +import com.anthropic.models.beta.sessions.resources.BetaManagedAgentsFileResource; +import com.anthropic.models.beta.sessions.resources.ResourceAddParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceAddParams params = ResourceAddParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .betaManagedAgentsFileResourceParams(BetaManagedAgentsFileResourceParams.builder() + .fileId("file_011CNha8iCJcU1wXNR6q4V8w") + .type(BetaManagedAgentsFileResourceParams.Type.FILE) + .build()) + .build(); + BetaManagedAgentsFileResource betaManagedAgentsFileResource = client.beta().sessions().resources().add(params); + } +} +``` + +## List + +`ResourceListPage beta().sessions().resources().list(ResourceListParamsparams = ResourceListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `ResourceListParams params` + + - `Optional sessionId` + + - `Optional limit` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `Optional page` + + Opaque cursor from a previous response's next_page field. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsSessionResource: A class that can be one of several variants.union` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.resources.ResourceListPage; +import com.anthropic.models.beta.sessions.resources.ResourceListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceListPage page = client.beta().sessions().resources().list("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` + +## Retrieve + +`ResourceRetrieveResponse beta().sessions().resources().retrieve(ResourceRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `ResourceRetrieveParams params` + + - `String sessionId` + + - `Optional resourceId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class ResourceRetrieveResponse: A class that can be one of several variants.union` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.resources.ResourceRetrieveParams; +import com.anthropic.models.beta.sessions.resources.ResourceRetrieveResponse; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceRetrieveParams params = ResourceRetrieveParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .resourceId("sesrsc_011CZkZBJq5dWxk9fVLNcPht") + .build(); + ResourceRetrieveResponse resource = client.beta().sessions().resources().retrieve(params); + } +} +``` + +## Update + +`ResourceUpdateResponse beta().sessions().resources().update(ResourceUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `ResourceUpdateParams params` + + - `String sessionId` + + - `Optional resourceId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `String authorizationToken` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +### Returns + +- `class ResourceUpdateResponse: A class that can be one of several variants.union` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.resources.ResourceUpdateParams; +import com.anthropic.models.beta.sessions.resources.ResourceUpdateResponse; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceUpdateParams params = ResourceUpdateParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .resourceId("sesrsc_011CZkZBJq5dWxk9fVLNcPht") + .authorizationToken("ghp_exampletoken") + .build(); + ResourceUpdateResponse resource = client.beta().sessions().resources().update(params); + } +} +``` + +## Delete + +`BetaManagedAgentsDeleteSessionResource beta().sessions().resources().delete(ResourceDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `ResourceDeleteParams params` + + - `String sessionId` + + - `Optional resourceId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource:` + + Confirmation of resource deletion. + + - `String id` + + - `Type type` + + - `SESSION_RESOURCE_DELETED("session_resource_deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.resources.BetaManagedAgentsDeleteSessionResource; +import com.anthropic.models.beta.sessions.resources.ResourceDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceDeleteParams params = ResourceDeleteParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .resourceId("sesrsc_011CZkZBJq5dWxk9fVLNcPht") + .build(); + BetaManagedAgentsDeleteSessionResource betaManagedAgentsDeleteSessionResource = client.beta().sessions().resources().delete(params); + } +} +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `class BetaManagedAgentsDeleteSessionResource:` + + Confirmation of resource deletion. + + - `String id` + + - `Type type` + + - `SESSION_RESOURCE_DELETED("session_resource_deleted")` + +### Beta Managed Agents File Resource + +- `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + +### Beta Managed Agents Session Resource + +- `class BetaManagedAgentsSessionResource: A class that can be one of several variants.union` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format diff --git a/content/en/api/java/beta/sessions/archive.md b/content/en/api/java/beta/sessions/archive.md new file mode 100644 index 000000000..572b614e0 --- /dev/null +++ b/content/en/api/java/beta/sessions/archive.md @@ -0,0 +1,502 @@ +## Archive + +`BetaManagedAgentsSession beta().sessions().archive(SessionArchiveParamsparams = SessionArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `SessionArchiveParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `String id` + + - `BetaManagedAgentsSessionAgent agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `String id` + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `long version` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String environmentId` + + - `Metadata metadata` + + - `List resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionStats stats` + + Timing statistics for a session. + + - `Optional activeSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Optional durationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status status` + + SessionStatus enum + + - `RESCHEDULING("rescheduling")` + + - `RUNNING("running")` + + - `IDLE("idle")` + + - `TERMINATED("terminated")` + + - `Optional title` + + - `Type type` + + - `SESSION("session")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionUsage usage` + + Cumulative token usage for a session across all turns. + + - `Optional cacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Optional cacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Optional inputTokens` + + Total input tokens consumed across all turns. + + - `Optional outputTokens` + + Total output tokens generated across all turns. + + - `List vaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsSession; +import com.anthropic.models.beta.sessions.SessionArchiveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsSession betaManagedAgentsSession = client.beta().sessions().archive("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` diff --git a/content/en/api/java/beta/sessions/create.md b/content/en/api/java/beta/sessions/create.md new file mode 100644 index 000000000..c529119c6 --- /dev/null +++ b/content/en/api/java/beta/sessions/create.md @@ -0,0 +1,606 @@ +## Create + +`BetaManagedAgentsSession beta().sessions().create(SessionCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `SessionCreateParams params` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Agent agent` + + Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `String` + + - `class BetaManagedAgentsAgentParams:` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `String id` + + The `agent` ID. + + - `Type type` + + - `AGENT("agent")` + + - `Optional version` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + + - `String environmentId` + + ID of the `environment` defining the container configuration for this session. + + - `Optional metadata` + + Arbitrary key-value metadata attached to the session. + + - `Optional> resources` + + Resources (e.g. repositories, files) to mount into the session's container. + + - `class BetaManagedAgentsGitHubRepositoryResourceParams:` + + Mount a GitHub repository into the session's container. + + - `String authorizationToken` + + GitHub authorization token used to clone the repository. + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `String url` + + Github URL of the repository + + - `Optional checkout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `Optional mountPath` + + Mount path in the container. Defaults to `/workspace/`. + + - `class BetaManagedAgentsFileResourceParams:` + + Mount a file uploaded via the Files API into the session. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Optional mountPath` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `Optional title` + + Human-readable session title. + + - `Optional> vaultIds` + + Vault IDs for stored credentials the agent can use during the session. + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `String id` + + - `BetaManagedAgentsSessionAgent agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `String id` + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `long version` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String environmentId` + + - `Metadata metadata` + + - `List resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionStats stats` + + Timing statistics for a session. + + - `Optional activeSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Optional durationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status status` + + SessionStatus enum + + - `RESCHEDULING("rescheduling")` + + - `RUNNING("running")` + + - `IDLE("idle")` + + - `TERMINATED("terminated")` + + - `Optional title` + + - `Type type` + + - `SESSION("session")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionUsage usage` + + Cumulative token usage for a session across all turns. + + - `Optional cacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Optional cacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Optional inputTokens` + + Total input tokens consumed across all turns. + + - `Optional outputTokens` + + Total output tokens generated across all turns. + + - `List vaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsSession; +import com.anthropic.models.beta.sessions.SessionCreateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + SessionCreateParams params = SessionCreateParams.builder() + .agent("agent_011CZkYpogX7uDKUyvBTophP") + .environmentId("env_011CZkZ9X2dpNyB7HsEFoRfW") + .build(); + BetaManagedAgentsSession betaManagedAgentsSession = client.beta().sessions().create(params); + } +} +``` diff --git a/content/en/api/java/beta/sessions/delete.md b/content/en/api/java/beta/sessions/delete.md new file mode 100644 index 000000000..5ae4533d0 --- /dev/null +++ b/content/en/api/java/beta/sessions/delete.md @@ -0,0 +1,92 @@ +## Delete + +`BetaManagedAgentsDeletedSession beta().sessions().delete(SessionDeleteParamsparams = SessionDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `SessionDeleteParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsDeletedSession:` + + Confirmation that a `session` has been permanently deleted. + + - `String id` + + - `Type type` + + - `SESSION_DELETED("session_deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsDeletedSession; +import com.anthropic.models.beta.sessions.SessionDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsDeletedSession betaManagedAgentsDeletedSession = client.beta().sessions().delete("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` diff --git a/content/en/api/java/beta/sessions/events.md b/content/en/api/java/beta/sessions/events.md new file mode 100644 index 000000000..3cb0b412f --- /dev/null +++ b/content/en/api/java/beta/sessions/events.md @@ -0,0 +1,9655 @@ +# Events + +## List + +`EventListPage beta().sessions().events().list(EventListParamsparams = EventListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `EventListParams params` + + - `Optional sessionId` + + - `Optional limit` + + Query parameter for limit + + - `Optional order` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `ASC("asc")` + + - `DESC("desc")` + + - `Optional page` + + Opaque pagination cursor from a previous response's next_page. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsSessionEvent: A class that can be one of several variants.union` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the custom tool being called. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of text blocks comprising the agent response. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MESSAGE("agent.message")` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THINKING("agent.thinking")` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String mcpServerName` + + Name of the MCP server providing the tool. + + - `String name` + + Name of the MCP tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `String id` + + Unique identifier for this event. + + - `String mcpToolUseId` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the agent tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_TOOL_USE("agent.tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `String toolUseId` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type type` + + - `AGENT_TOOL_RESULT("agent.tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `String id` + + Unique identifier for this event. + + - `Error error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_ERROR("session.error")` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RUNNING("session.status_running")` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `StopReason stopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + + - `Type type` + + - `SESSION_STATUS_IDLE("session.status_idle")` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_TERMINATED("session.status_terminated")` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_START("span.model_request_start")` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `String id` + + Unique identifier for this event. + + - `Optional isError` + + Whether the model request resulted in an error. + + - `String modelRequestStartId` + + The id of the corresponding `span.model_request_start` event. + + - `BetaManagedAgentsSpanModelUsage modelUsage` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_END("span.model_request_end")` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_DELETED("session.deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.events.EventListPage; +import com.anthropic.models.beta.sessions.events.EventListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + EventListPage page = client.beta().sessions().events().list("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` + +## Send + +`BetaManagedAgentsSendSessionEvents beta().sessions().events().send(EventSendParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `EventSendParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `List events` + + Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `List content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + +### Returns + +- `class BetaManagedAgentsSendSessionEvents:` + + Events that were successfully sent to the session. + + - `Optional> data` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsSendSessionEvents; +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsTextBlock; +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams; +import com.anthropic.models.beta.sessions.events.EventSendParams; +import java.util.List; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + EventSendParams params = EventSendParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .addUserMessageEvent(List.of(BetaManagedAgentsUserMessageEventParams.Content.ofText(BetaManagedAgentsTextBlock.builder() + .text("Where is my order #1234?") + .type(BetaManagedAgentsTextBlock.Type.TEXT) + .build()))) + .build(); + BetaManagedAgentsSendSessionEvents betaManagedAgentsSendSessionEvents = client.beta().sessions().events().send(params); + } +} +``` + +## Stream + +`BetaManagedAgentsStreamSessionEvents beta().sessions().events().streamStreaming(EventStreamParamsparams = EventStreamParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `EventStreamParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the custom tool being called. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of text blocks comprising the agent response. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MESSAGE("agent.message")` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THINKING("agent.thinking")` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String mcpServerName` + + Name of the MCP server providing the tool. + + - `String name` + + Name of the MCP tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `String id` + + Unique identifier for this event. + + - `String mcpToolUseId` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the agent tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_TOOL_USE("agent.tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `String toolUseId` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type type` + + - `AGENT_TOOL_RESULT("agent.tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `String id` + + Unique identifier for this event. + + - `Error error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_ERROR("session.error")` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RUNNING("session.status_running")` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `StopReason stopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + + - `Type type` + + - `SESSION_STATUS_IDLE("session.status_idle")` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_TERMINATED("session.status_terminated")` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_START("span.model_request_start")` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `String id` + + Unique identifier for this event. + + - `Optional isError` + + Whether the model request resulted in an error. + + - `String modelRequestStartId` + + The id of the corresponding `span.model_request_start` event. + + - `BetaManagedAgentsSpanModelUsage modelUsage` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_END("span.model_request_end")` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_DELETED("session.deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.core.http.StreamResponse; +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsStreamSessionEvents; +import com.anthropic.models.beta.sessions.events.EventStreamParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + StreamResponse betaManagedAgentsStreamSessionEvents = client.beta().sessions().events().streamStreaming("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the custom tool being called. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `String id` + + Unique identifier for this event. + + - `String mcpToolUseId` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String mcpServerName` + + Name of the MCP server providing the tool. + + - `String name` + + Name of the MCP tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + +### Beta Managed Agents Agent Message Event + +- `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of text blocks comprising the agent response. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MESSAGE("agent.message")` + +### Beta Managed Agents Agent Thinking Event + +- `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THINKING("agent.thinking")` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")` + +### Beta Managed Agents Agent Tool Result Event + +- `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `String toolUseId` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type type` + + - `AGENT_TOOL_RESULT("agent.tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the agent tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_TOOL_USE("agent.tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + +### Beta Managed Agents Base64 Document Source + +- `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + +### Beta Managed Agents Base64 Image Source + +- `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + +### Beta Managed Agents Billing Error + +- `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + +### Beta Managed Agents Document Block + +- `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + +### Beta Managed Agents Event Params + +- `class BetaManagedAgentsEventParams: A class that can be one of several variants.union` + + Union type for event parameters that can be sent to a session. + + - `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `List content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + +### Beta Managed Agents File Image Source + +- `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + +### Beta Managed Agents Image Block + +- `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + +### Beta Managed Agents MCP Authentication Failed Error + +- `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + +### Beta Managed Agents MCP Connection Failed Error + +- `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + +### Beta Managed Agents Model Overloaded Error + +- `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + +### Beta Managed Agents Model Rate Limited Error + +- `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + +### Beta Managed Agents Model Request Failed Error + +- `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + +### Beta Managed Agents Plain Text Document Source + +- `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + +### Beta Managed Agents Retry Status Exhausted + +- `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + +### Beta Managed Agents Retry Status Retrying + +- `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + +### Beta Managed Agents Retry Status Terminal + +- `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + +### Beta Managed Agents Send Session Events + +- `class BetaManagedAgentsSendSessionEvents:` + + Events that were successfully sent to the session. + + - `Optional> data` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_DELETED("session.deleted")` + +### Beta Managed Agents Session End Turn + +- `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + +### Beta Managed Agents Session Error Event + +- `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `String id` + + Unique identifier for this event. + + - `Error error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_ERROR("session.error")` + +### Beta Managed Agents Session Event + +- `class BetaManagedAgentsSessionEvent: A class that can be one of several variants.union` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the custom tool being called. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of text blocks comprising the agent response. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MESSAGE("agent.message")` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THINKING("agent.thinking")` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String mcpServerName` + + Name of the MCP server providing the tool. + + - `String name` + + Name of the MCP tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `String id` + + Unique identifier for this event. + + - `String mcpToolUseId` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the agent tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_TOOL_USE("agent.tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `String toolUseId` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type type` + + - `AGENT_TOOL_RESULT("agent.tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `String id` + + Unique identifier for this event. + + - `Error error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_ERROR("session.error")` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RUNNING("session.status_running")` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `StopReason stopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + + - `Type type` + + - `SESSION_STATUS_IDLE("session.status_idle")` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_TERMINATED("session.status_terminated")` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_START("span.model_request_start")` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `String id` + + Unique identifier for this event. + + - `Optional isError` + + Whether the model request resulted in an error. + + - `String modelRequestStartId` + + The id of the corresponding `span.model_request_start` event. + + - `BetaManagedAgentsSpanModelUsage modelUsage` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_END("span.model_request_end")` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_DELETED("session.deleted")` + +### Beta Managed Agents Session Requires Action + +- `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + +### Beta Managed Agents Session Retries Exhausted + +- `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + +### Beta Managed Agents Session Status Idle Event + +- `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `StopReason stopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + + - `Type type` + + - `SESSION_STATUS_IDLE("session.status_idle")` + +### Beta Managed Agents Session Status Rescheduled Event + +- `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")` + +### Beta Managed Agents Session Status Running Event + +- `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RUNNING("session.status_running")` + +### Beta Managed Agents Session Status Terminated Event + +- `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_TERMINATED("session.status_terminated")` + +### Beta Managed Agents Span Model Request End Event + +- `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `String id` + + Unique identifier for this event. + + - `Optional isError` + + Whether the model request resulted in an error. + + - `String modelRequestStartId` + + The id of the corresponding `span.model_request_start` event. + + - `BetaManagedAgentsSpanModelUsage modelUsage` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_END("span.model_request_end")` + +### Beta Managed Agents Span Model Request Start Event + +- `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_START("span.model_request_start")` + +### Beta Managed Agents Span Model Usage + +- `class BetaManagedAgentsSpanModelUsage:` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + +### Beta Managed Agents Stream Session Events + +- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the custom tool being called. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of text blocks comprising the agent response. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MESSAGE("agent.message")` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THINKING("agent.thinking")` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String mcpServerName` + + Name of the MCP server providing the tool. + + - `String name` + + Name of the MCP tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `String id` + + Unique identifier for this event. + + - `String mcpToolUseId` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the agent tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_TOOL_USE("agent.tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `String toolUseId` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type type` + + - `AGENT_TOOL_RESULT("agent.tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `String id` + + Unique identifier for this event. + + - `Error error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_ERROR("session.error")` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RUNNING("session.status_running")` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `StopReason stopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + + - `Type type` + + - `SESSION_STATUS_IDLE("session.status_idle")` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_TERMINATED("session.status_terminated")` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_START("span.model_request_start")` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `String id` + + Unique identifier for this event. + + - `Optional isError` + + Whether the model request resulted in an error. + + - `String modelRequestStartId` + + The id of the corresponding `span.model_request_start` event. + + - `BetaManagedAgentsSpanModelUsage modelUsage` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_END("span.model_request_end")` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_DELETED("session.deleted")` + +### Beta Managed Agents Text Block + +- `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + +### Beta Managed Agents Unknown Error + +- `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + +### Beta Managed Agents URL Document Source + +- `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + +### Beta Managed Agents User Message Event + +- `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `List content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + +### Beta Managed Agents User Tool Confirmation Event + +- `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. diff --git a/content/en/api/java/beta/sessions/events/list.md b/content/en/api/java/beta/sessions/events/list.md new file mode 100644 index 000000000..38b46ec1f --- /dev/null +++ b/content/en/api/java/beta/sessions/events/list.md @@ -0,0 +1,1466 @@ +## List + +`EventListPage beta().sessions().events().list(EventListParamsparams = EventListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `EventListParams params` + + - `Optional sessionId` + + - `Optional limit` + + Query parameter for limit + + - `Optional order` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `ASC("asc")` + + - `DESC("desc")` + + - `Optional page` + + Opaque pagination cursor from a previous response's next_page. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsSessionEvent: A class that can be one of several variants.union` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the custom tool being called. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of text blocks comprising the agent response. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MESSAGE("agent.message")` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THINKING("agent.thinking")` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String mcpServerName` + + Name of the MCP server providing the tool. + + - `String name` + + Name of the MCP tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `String id` + + Unique identifier for this event. + + - `String mcpToolUseId` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the agent tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_TOOL_USE("agent.tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `String toolUseId` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type type` + + - `AGENT_TOOL_RESULT("agent.tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `String id` + + Unique identifier for this event. + + - `Error error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_ERROR("session.error")` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RUNNING("session.status_running")` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `StopReason stopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + + - `Type type` + + - `SESSION_STATUS_IDLE("session.status_idle")` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_TERMINATED("session.status_terminated")` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_START("span.model_request_start")` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `String id` + + Unique identifier for this event. + + - `Optional isError` + + Whether the model request resulted in an error. + + - `String modelRequestStartId` + + The id of the corresponding `span.model_request_start` event. + + - `BetaManagedAgentsSpanModelUsage modelUsage` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_END("span.model_request_end")` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_DELETED("session.deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.events.EventListPage; +import com.anthropic.models.beta.sessions.events.EventListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + EventListPage page = client.beta().sessions().events().list("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` diff --git a/content/en/api/java/beta/sessions/events/send.md b/content/en/api/java/beta/sessions/events/send.md new file mode 100644 index 000000000..5b8ace3e3 --- /dev/null +++ b/content/en/api/java/beta/sessions/events/send.md @@ -0,0 +1,832 @@ +## Send + +`BetaManagedAgentsSendSessionEvents beta().sessions().events().send(EventSendParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `EventSendParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `List events` + + Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams:` + + Parameters for sending a user message to the session. + + - `List content` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `class BetaManagedAgentsUserInterruptEventParams:` + + Parameters for sending an interrupt to pause the agent. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `class BetaManagedAgentsUserToolConfirmationEventParams:` + + Parameters for confirming or denying a tool execution request. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams:` + + Parameters for providing the result of a custom tool execution. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + +### Returns + +- `class BetaManagedAgentsSendSessionEvents:` + + Events that were successfully sent to the session. + + - `Optional> data` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsSendSessionEvents; +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsTextBlock; +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams; +import com.anthropic.models.beta.sessions.events.EventSendParams; +import java.util.List; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + EventSendParams params = EventSendParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .addUserMessageEvent(List.of(BetaManagedAgentsUserMessageEventParams.Content.ofText(BetaManagedAgentsTextBlock.builder() + .text("Where is my order #1234?") + .type(BetaManagedAgentsTextBlock.Type.TEXT) + .build()))) + .build(); + BetaManagedAgentsSendSessionEvents betaManagedAgentsSendSessionEvents = client.beta().sessions().events().send(params); + } +} +``` diff --git a/content/en/api/java/beta/sessions/events/stream.md b/content/en/api/java/beta/sessions/events/stream.md new file mode 100644 index 000000000..7cc23147e --- /dev/null +++ b/content/en/api/java/beta/sessions/events/stream.md @@ -0,0 +1,1451 @@ +## Stream + +`BetaManagedAgentsStreamSessionEvents beta().sessions().events().streamStreaming(EventStreamParamsparams = EventStreamParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `EventStreamParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent:` + + A user message event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Type type` + + - `USER_MESSAGE("user.message")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent:` + + An interrupt event that pauses agent execution and returns control to the user. + + - `String id` + + Unique identifier for this event. + + - `Type type` + + - `USER_INTERRUPT("user.interrupt")` + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent:` + + A tool confirmation event that approves or denies a pending tool execution. + + - `String id` + + Unique identifier for this event. + + - `Result result` + + UserToolConfirmationResult enum + + - `ALLOW("allow")` + + - `DENY("deny")` + + - `String toolUseId` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_TOOL_CONFIRMATION("user.tool_confirmation")` + + - `Optional denyMessage` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent:` + + Event sent by the client providing the result of a custom tool execution. + + - `String id` + + Unique identifier for this event. + + - `String customToolUseId` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `Type type` + + - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `Optional processedAt` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent:` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the custom tool being called. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")` + + - `class BetaManagedAgentsAgentMessageEvent:` + + An agent response event in the session conversation. + + - `String id` + + Unique identifier for this event. + + - `List content` + + Array of text blocks comprising the agent response. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MESSAGE("agent.message")` + + - `class BetaManagedAgentsAgentThinkingEvent:` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THINKING("agent.thinking")` + + - `class BetaManagedAgentsAgentMcpToolUseEvent:` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String mcpServerName` + + Name of the MCP server providing the tool. + + - `String name` + + Name of the MCP tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentMcpToolResultEvent:` + + Event representing the result of an MCP tool execution. + + - `String id` + + Unique identifier for this event. + + - `String mcpToolUseId` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent:` + + Event emitted when the agent invokes a built-in agent tool. + + - `String id` + + Unique identifier for this event. + + - `Input input` + + Input parameters for the tool call. + + - `String name` + + Name of the agent tool being used. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_TOOL_USE("agent.tool_use")` + + - `Optional evaluatedPermission` + + AgentEvaluatedPermission enum + + - `ALLOW("allow")` + + - `ASK("ask")` + + - `DENY("deny")` + + - `class BetaManagedAgentsAgentToolResultEvent:` + + Event representing the result of an agent tool execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `String toolUseId` + + The id of the `agent.tool_use` event this result corresponds to. + + - `Type type` + + - `AGENT_TOOL_RESULT("agent.tool_result")` + + - `Optional> content` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock:` + + Regular text content. + + - `String text` + + The text content. + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsImageBlock:` + + Image content specified directly as base64 data or as a reference via a URL. + + - `Source source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource:` + + Base64-encoded image data. + + - `String data` + + Base64-encoded image data. + + - `String mediaType` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsUrlImageSource:` + + Image referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource:` + + Image referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `IMAGE("image")` + + - `class BetaManagedAgentsDocumentBlock:` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `Source source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource:` + + Base64-encoded document data. + + - `String data` + + Base64-encoded document data. + + - `String mediaType` + + MIME type of the document (e.g., "application/pdf"). + + - `Type type` + + - `BASE64("base64")` + + - `class BetaManagedAgentsPlainTextDocumentSource:` + + Plain text document content. + + - `String data` + + The plain text content. + + - `MediaType mediaType` + + MIME type of the text content. Must be "text/plain". + + - `TEXT_PLAIN("text/plain")` + + - `Type type` + + - `TEXT("text")` + + - `class BetaManagedAgentsUrlDocumentSource:` + + Document referenced by URL. + + - `Type type` + + - `URL("url")` + + - `String url` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource:` + + Document referenced by file ID. + + - `String fileId` + + ID of a previously uploaded file. + + - `Type type` + + - `FILE("file")` + + - `Type type` + + - `DOCUMENT("document")` + + - `Optional context` + + Additional context about the document for the model. + + - `Optional title` + + The title of the document. + + - `Optional isError` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent:` + + Indicates that context compaction (summarization) occurred during the session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")` + + - `class BetaManagedAgentsSessionErrorEvent:` + + An error event indicating a problem occurred during session execution. + + - `String id` + + Unique identifier for this event. + + - `Error error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError:` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `UNKNOWN_ERROR("unknown_error")` + + - `class BetaManagedAgentsModelOverloadedError:` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_OVERLOADED_ERROR("model_overloaded_error")` + + - `class BetaManagedAgentsModelRateLimitedError:` + + The model request was rate-limited. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")` + + - `class BetaManagedAgentsModelRequestFailedError:` + + A model request failed for a reason other than overload or rate-limiting. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")` + + - `class BetaManagedAgentsMcpConnectionFailedError:` + + Failed to connect to an MCP server. + + - `String mcpServerName` + + Name of the MCP server that failed to connect. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")` + + - `class BetaManagedAgentsMcpAuthenticationFailedError:` + + Authentication to an MCP server failed. + + - `String mcpServerName` + + Name of the MCP server that failed authentication. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")` + + - `class BetaManagedAgentsBillingError:` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `String message` + + Human-readable error description. + + - `RetryStatus retryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying:` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `Type type` + + - `RETRYING("retrying")` + + - `class BetaManagedAgentsRetryStatusExhausted:` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `Type type` + + - `EXHAUSTED("exhausted")` + + - `class BetaManagedAgentsRetryStatusTerminal:` + + The session encountered a terminal error and will transition to `terminated` state. + + - `Type type` + + - `TERMINAL("terminal")` + + - `Type type` + + - `BILLING_ERROR("billing_error")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_ERROR("session.error")` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent:` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")` + + - `class BetaManagedAgentsSessionStatusRunningEvent:` + + Indicates the session is actively running and the agent is working. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_RUNNING("session.status_running")` + + - `class BetaManagedAgentsSessionStatusIdleEvent:` + + Indicates the agent has paused and is awaiting user input. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `StopReason stopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn:` + + The agent completed its turn naturally and is ready for the next user message. + + - `Type type` + + - `END_TURN("end_turn")` + + - `class BetaManagedAgentsSessionRequiresAction:` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `List eventIds` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `Type type` + + - `REQUIRES_ACTION("requires_action")` + + - `class BetaManagedAgentsSessionRetriesExhausted:` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `Type type` + + - `RETRIES_EXHAUSTED("retries_exhausted")` + + - `Type type` + + - `SESSION_STATUS_IDLE("session.status_idle")` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent:` + + Indicates the session has terminated, either due to an error or completion. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_STATUS_TERMINATED("session.status_terminated")` + + - `class BetaManagedAgentsSpanModelRequestStartEvent:` + + Emitted when a model request is initiated by the agent. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_START("span.model_request_start")` + + - `class BetaManagedAgentsSpanModelRequestEndEvent:` + + Emitted when a model request completes. + + - `String id` + + Unique identifier for this event. + + - `Optional isError` + + Whether the model request resulted in an error. + + - `String modelRequestStartId` + + The id of the corresponding `span.model_request_start` event. + + - `BetaManagedAgentsSpanModelUsage modelUsage` + + Token usage for a single model request. + + - `long cacheCreationInputTokens` + + Tokens used to create prompt cache in this request. + + - `long cacheReadInputTokens` + + Tokens read from prompt cache in this request. + + - `long inputTokens` + + Input tokens consumed by this request. + + - `long outputTokens` + + Output tokens generated by this request. + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SPAN_MODEL_REQUEST_END("span.model_request_end")` + + - `class BetaManagedAgentsSessionDeletedEvent:` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `String id` + + Unique identifier for this event. + + - `LocalDateTime processedAt` + + A timestamp in RFC 3339 format + + - `Type type` + + - `SESSION_DELETED("session.deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.core.http.StreamResponse; +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsStreamSessionEvents; +import com.anthropic.models.beta.sessions.events.EventStreamParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + StreamResponse betaManagedAgentsStreamSessionEvents = client.beta().sessions().events().streamStreaming("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` diff --git a/content/en/api/java/beta/sessions/list.md b/content/en/api/java/beta/sessions/list.md new file mode 100644 index 000000000..e9b9576bd --- /dev/null +++ b/content/en/api/java/beta/sessions/list.md @@ -0,0 +1,544 @@ +## List + +`SessionListPage beta().sessions().list(SessionListParamsparams = SessionListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `SessionListParams params` + + - `Optional agentId` + + Filter sessions created with this agent ID. + + - `Optional agentVersion` + + Filter by agent version. Only applies when agent_id is also set. + + - `Optional createdAtGt` + + Return sessions created after this time (exclusive). + + - `Optional createdAtGte` + + Return sessions created at or after this time (inclusive). + + - `Optional createdAtLt` + + Return sessions created before this time (exclusive). + + - `Optional createdAtLte` + + Return sessions created at or before this time (inclusive). + + - `Optional includeArchived` + + When true, includes archived sessions. Default: false (exclude archived). + + - `Optional limit` + + Maximum number of results to return. + + - `Optional order` + + Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `ASC("asc")` + + - `DESC("desc")` + + - `Optional page` + + Opaque pagination cursor from a previous response's next_page. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `String id` + + - `BetaManagedAgentsSessionAgent agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `String id` + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `long version` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String environmentId` + + - `Metadata metadata` + + - `List resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionStats stats` + + Timing statistics for a session. + + - `Optional activeSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Optional durationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status status` + + SessionStatus enum + + - `RESCHEDULING("rescheduling")` + + - `RUNNING("running")` + + - `IDLE("idle")` + + - `TERMINATED("terminated")` + + - `Optional title` + + - `Type type` + + - `SESSION("session")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionUsage usage` + + Cumulative token usage for a session across all turns. + + - `Optional cacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Optional cacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Optional inputTokens` + + Total input tokens consumed across all turns. + + - `Optional outputTokens` + + Total output tokens generated across all turns. + + - `List vaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.SessionListPage; +import com.anthropic.models.beta.sessions.SessionListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + SessionListPage page = client.beta().sessions().list(); + } +} +``` diff --git a/content/en/api/java/beta/sessions/resources.md b/content/en/api/java/beta/sessions/resources.md new file mode 100644 index 000000000..c488b6063 --- /dev/null +++ b/content/en/api/java/beta/sessions/resources.md @@ -0,0 +1,831 @@ +# Resources + +## Add + +`BetaManagedAgentsFileResource beta().sessions().resources().add(ResourceAddParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `ResourceAddParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `BetaManagedAgentsFileResourceParams betaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + +### Returns + +- `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsFileResourceParams; +import com.anthropic.models.beta.sessions.resources.BetaManagedAgentsFileResource; +import com.anthropic.models.beta.sessions.resources.ResourceAddParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceAddParams params = ResourceAddParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .betaManagedAgentsFileResourceParams(BetaManagedAgentsFileResourceParams.builder() + .fileId("file_011CNha8iCJcU1wXNR6q4V8w") + .type(BetaManagedAgentsFileResourceParams.Type.FILE) + .build()) + .build(); + BetaManagedAgentsFileResource betaManagedAgentsFileResource = client.beta().sessions().resources().add(params); + } +} +``` + +## List + +`ResourceListPage beta().sessions().resources().list(ResourceListParamsparams = ResourceListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `ResourceListParams params` + + - `Optional sessionId` + + - `Optional limit` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `Optional page` + + Opaque cursor from a previous response's next_page field. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsSessionResource: A class that can be one of several variants.union` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.resources.ResourceListPage; +import com.anthropic.models.beta.sessions.resources.ResourceListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceListPage page = client.beta().sessions().resources().list("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` + +## Retrieve + +`ResourceRetrieveResponse beta().sessions().resources().retrieve(ResourceRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `ResourceRetrieveParams params` + + - `String sessionId` + + - `Optional resourceId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class ResourceRetrieveResponse: A class that can be one of several variants.union` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.resources.ResourceRetrieveParams; +import com.anthropic.models.beta.sessions.resources.ResourceRetrieveResponse; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceRetrieveParams params = ResourceRetrieveParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .resourceId("sesrsc_011CZkZBJq5dWxk9fVLNcPht") + .build(); + ResourceRetrieveResponse resource = client.beta().sessions().resources().retrieve(params); + } +} +``` + +## Update + +`ResourceUpdateResponse beta().sessions().resources().update(ResourceUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `ResourceUpdateParams params` + + - `String sessionId` + + - `Optional resourceId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `String authorizationToken` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +### Returns + +- `class ResourceUpdateResponse: A class that can be one of several variants.union` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.resources.ResourceUpdateParams; +import com.anthropic.models.beta.sessions.resources.ResourceUpdateResponse; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceUpdateParams params = ResourceUpdateParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .resourceId("sesrsc_011CZkZBJq5dWxk9fVLNcPht") + .authorizationToken("ghp_exampletoken") + .build(); + ResourceUpdateResponse resource = client.beta().sessions().resources().update(params); + } +} +``` + +## Delete + +`BetaManagedAgentsDeleteSessionResource beta().sessions().resources().delete(ResourceDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `ResourceDeleteParams params` + + - `String sessionId` + + - `Optional resourceId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource:` + + Confirmation of resource deletion. + + - `String id` + + - `Type type` + + - `SESSION_RESOURCE_DELETED("session_resource_deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.resources.BetaManagedAgentsDeleteSessionResource; +import com.anthropic.models.beta.sessions.resources.ResourceDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceDeleteParams params = ResourceDeleteParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .resourceId("sesrsc_011CZkZBJq5dWxk9fVLNcPht") + .build(); + BetaManagedAgentsDeleteSessionResource betaManagedAgentsDeleteSessionResource = client.beta().sessions().resources().delete(params); + } +} +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `class BetaManagedAgentsDeleteSessionResource:` + + Confirmation of resource deletion. + + - `String id` + + - `Type type` + + - `SESSION_RESOURCE_DELETED("session_resource_deleted")` + +### Beta Managed Agents File Resource + +- `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + +### Beta Managed Agents Session Resource + +- `class BetaManagedAgentsSessionResource: A class that can be one of several variants.union` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format diff --git a/content/en/api/java/beta/sessions/resources/add.md b/content/en/api/java/beta/sessions/resources/add.md new file mode 100644 index 000000000..6110a9aa4 --- /dev/null +++ b/content/en/api/java/beta/sessions/resources/add.md @@ -0,0 +1,114 @@ +## Add + +`BetaManagedAgentsFileResource beta().sessions().resources().add(ResourceAddParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `ResourceAddParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `BetaManagedAgentsFileResourceParams betaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + +### Returns + +- `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsFileResourceParams; +import com.anthropic.models.beta.sessions.resources.BetaManagedAgentsFileResource; +import com.anthropic.models.beta.sessions.resources.ResourceAddParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceAddParams params = ResourceAddParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .betaManagedAgentsFileResourceParams(BetaManagedAgentsFileResourceParams.builder() + .fileId("file_011CNha8iCJcU1wXNR6q4V8w") + .type(BetaManagedAgentsFileResourceParams.Type.FILE) + .build()) + .build(); + BetaManagedAgentsFileResource betaManagedAgentsFileResource = client.beta().sessions().resources().add(params); + } +} +``` diff --git a/content/en/api/java/beta/sessions/resources/delete.md b/content/en/api/java/beta/sessions/resources/delete.md new file mode 100644 index 000000000..b178bb2f0 --- /dev/null +++ b/content/en/api/java/beta/sessions/resources/delete.md @@ -0,0 +1,98 @@ +## Delete + +`BetaManagedAgentsDeleteSessionResource beta().sessions().resources().delete(ResourceDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `ResourceDeleteParams params` + + - `String sessionId` + + - `Optional resourceId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource:` + + Confirmation of resource deletion. + + - `String id` + + - `Type type` + + - `SESSION_RESOURCE_DELETED("session_resource_deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.resources.BetaManagedAgentsDeleteSessionResource; +import com.anthropic.models.beta.sessions.resources.ResourceDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceDeleteParams params = ResourceDeleteParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .resourceId("sesrsc_011CZkZBJq5dWxk9fVLNcPht") + .build(); + BetaManagedAgentsDeleteSessionResource betaManagedAgentsDeleteSessionResource = client.beta().sessions().resources().delete(params); + } +} +``` diff --git a/content/en/api/java/beta/sessions/resources/list.md b/content/en/api/java/beta/sessions/resources/list.md new file mode 100644 index 000000000..fe790f31c --- /dev/null +++ b/content/en/api/java/beta/sessions/resources/list.md @@ -0,0 +1,154 @@ +## List + +`ResourceListPage beta().sessions().resources().list(ResourceListParamsparams = ResourceListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `ResourceListParams params` + + - `Optional sessionId` + + - `Optional limit` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `Optional page` + + Opaque cursor from a previous response's next_page field. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsSessionResource: A class that can be one of several variants.union` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.resources.ResourceListPage; +import com.anthropic.models.beta.sessions.resources.ResourceListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceListPage page = client.beta().sessions().resources().list("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` diff --git a/content/en/api/java/beta/sessions/resources/retrieve.md b/content/en/api/java/beta/sessions/resources/retrieve.md new file mode 100644 index 000000000..25bb09482 --- /dev/null +++ b/content/en/api/java/beta/sessions/resources/retrieve.md @@ -0,0 +1,154 @@ +## Retrieve + +`ResourceRetrieveResponse beta().sessions().resources().retrieve(ResourceRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `ResourceRetrieveParams params` + + - `String sessionId` + + - `Optional resourceId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class ResourceRetrieveResponse: A class that can be one of several variants.union` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.resources.ResourceRetrieveParams; +import com.anthropic.models.beta.sessions.resources.ResourceRetrieveResponse; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceRetrieveParams params = ResourceRetrieveParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .resourceId("sesrsc_011CZkZBJq5dWxk9fVLNcPht") + .build(); + ResourceRetrieveResponse resource = client.beta().sessions().resources().retrieve(params); + } +} +``` diff --git a/content/en/api/java/beta/sessions/resources/update.md b/content/en/api/java/beta/sessions/resources/update.md new file mode 100644 index 000000000..05ec8648f --- /dev/null +++ b/content/en/api/java/beta/sessions/resources/update.md @@ -0,0 +1,159 @@ +## Update + +`ResourceUpdateResponse beta().sessions().resources().update(ResourceUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `ResourceUpdateParams params` + + - `String sessionId` + + - `Optional resourceId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `String authorizationToken` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +### Returns + +- `class ResourceUpdateResponse: A class that can be one of several variants.union` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.resources.ResourceUpdateParams; +import com.anthropic.models.beta.sessions.resources.ResourceUpdateResponse; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + ResourceUpdateParams params = ResourceUpdateParams.builder() + .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7") + .resourceId("sesrsc_011CZkZBJq5dWxk9fVLNcPht") + .authorizationToken("ghp_exampletoken") + .build(); + ResourceUpdateResponse resource = client.beta().sessions().resources().update(params); + } +} +``` diff --git a/content/en/api/java/beta/sessions/retrieve.md b/content/en/api/java/beta/sessions/retrieve.md new file mode 100644 index 000000000..6f469400f --- /dev/null +++ b/content/en/api/java/beta/sessions/retrieve.md @@ -0,0 +1,502 @@ +## Retrieve + +`BetaManagedAgentsSession beta().sessions().retrieve(SessionRetrieveParamsparams = SessionRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `SessionRetrieveParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `String id` + + - `BetaManagedAgentsSessionAgent agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `String id` + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `long version` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String environmentId` + + - `Metadata metadata` + + - `List resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionStats stats` + + Timing statistics for a session. + + - `Optional activeSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Optional durationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status status` + + SessionStatus enum + + - `RESCHEDULING("rescheduling")` + + - `RUNNING("running")` + + - `IDLE("idle")` + + - `TERMINATED("terminated")` + + - `Optional title` + + - `Type type` + + - `SESSION("session")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionUsage usage` + + Cumulative token usage for a session across all turns. + + - `Optional cacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Optional cacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Optional inputTokens` + + Total input tokens consumed across all turns. + + - `Optional outputTokens` + + Total output tokens generated across all turns. + + - `List vaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsSession; +import com.anthropic.models.beta.sessions.SessionRetrieveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsSession betaManagedAgentsSession = client.beta().sessions().retrieve("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` diff --git a/content/en/api/java/beta/sessions/update.md b/content/en/api/java/beta/sessions/update.md new file mode 100644 index 000000000..b09a9343f --- /dev/null +++ b/content/en/api/java/beta/sessions/update.md @@ -0,0 +1,514 @@ +## Update + +`BetaManagedAgentsSession beta().sessions().update(SessionUpdateParamsparams = SessionUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `SessionUpdateParams params` + + - `Optional sessionId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Optional metadata` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + + - `Optional title` + + Human-readable session title. + + - `Optional> vaultIds` + + Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +### Returns + +- `class BetaManagedAgentsSession:` + + A Managed Agents `session`. + + - `String id` + + - `BetaManagedAgentsSessionAgent agent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `String id` + + - `Optional description` + + - `List mcpServers` + + - `String name` + + - `Type type` + + - `URL("url")` + + - `String url` + + - `BetaManagedAgentsModelConfig model` + + Model identifier and configuration. + + - `BetaManagedAgentsModel id` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` + + Most intelligent model for building agents and coding + + - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` + + Best combination of speed and intelligence + + - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")` + + Fastest model with near-frontier intelligence + + - `CLAUDE_OPUS_4_5("claude-opus-4-5")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")` + + Premium model combining maximum intelligence with practical performance + + - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")` + + High-performance model for agents and coding + + - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")` + + High-performance model for agents and coding + + - `Optional speed` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `STANDARD("standard")` + + - `FAST("fast")` + + - `String name` + + - `List skills` + + - `class BetaManagedAgentsAnthropicSkill:` + + A resolved Anthropic-managed skill. + + - `String skillId` + + - `Type type` + + - `ANTHROPIC("anthropic")` + + - `String version` + + - `class BetaManagedAgentsCustomSkill:` + + A resolved user-created custom skill. + + - `String skillId` + + - `Type type` + + - `CUSTOM("custom")` + + - `String version` + + - `Optional system` + + - `List tools` + + - `class BetaManagedAgentsAgentToolset20260401:` + + - `List configs` + + - `boolean enabled` + + - `Name name` + + Built-in agent tool identifier. + + - `BASH("bash")` + + - `EDIT("edit")` + + - `READ("read")` + + - `WRITE("write")` + + - `GLOB("glob")` + + - `GREP("grep")` + + - `WEB_FETCH("web_fetch")` + + - `WEB_SEARCH("web_search")` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` + + Resolved default configuration for agent tools. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `Type type` + + - `AGENT_TOOLSET_20260401("agent_toolset_20260401")` + + - `class BetaManagedAgentsMcpToolset:` + + - `List configs` + + - `boolean enabled` + + - `String name` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `boolean enabled` + + - `PermissionPolicy permissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy:` + + Tool calls are automatically approved without user confirmation. + + - `Type type` + + - `ALWAYS_ALLOW("always_allow")` + + - `class BetaManagedAgentsAlwaysAskPolicy:` + + Tool calls require user confirmation before execution. + + - `Type type` + + - `ALWAYS_ASK("always_ask")` + + - `String mcpServerName` + + - `Type type` + + - `MCP_TOOLSET("mcp_toolset")` + + - `class BetaManagedAgentsCustomTool:` + + A custom tool as returned in API responses. + + - `String description` + + - `BetaManagedAgentsCustomToolInputSchema inputSchema` + + JSON Schema for custom tool input parameters. + + - `Optional properties` + + JSON Schema properties defining the tool's input parameters. + + - `Optional> required` + + List of required property names. + + - `Optional type` + + Must be 'object' for tool input schemas. + + - `OBJECT("object")` + + - `String name` + + - `Type type` + + - `CUSTOM("custom")` + + - `Type type` + + - `AGENT("agent")` + + - `long version` + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String environmentId` + + - `Metadata metadata` + + - `List resources` + + - `class BetaManagedAgentsGitHubRepositoryResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String mountPath` + + - `Type type` + + - `GITHUB_REPOSITORY("github_repository")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String url` + + - `Optional checkout` + + - `class BetaManagedAgentsBranchCheckout:` + + - `String name` + + Branch name to check out. + + - `Type type` + + - `BRANCH("branch")` + + - `class BetaManagedAgentsCommitCheckout:` + + - `String sha` + + Full commit SHA to check out. + + - `Type type` + + - `COMMIT("commit")` + + - `class BetaManagedAgentsFileResource:` + + - `String id` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String fileId` + + - `String mountPath` + + - `Type type` + + - `FILE("file")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionStats stats` + + Timing statistics for a session. + + - `Optional activeSeconds` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `Optional durationSeconds` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `Status status` + + SessionStatus enum + + - `RESCHEDULING("rescheduling")` + + - `RUNNING("running")` + + - `IDLE("idle")` + + - `TERMINATED("terminated")` + + - `Optional title` + + - `Type type` + + - `SESSION("session")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsSessionUsage usage` + + Cumulative token usage for a session across all turns. + + - `Optional cacheCreation` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `Optional ephemeral1hInputTokens` + + Tokens used to create 1-hour ephemeral cache entries. + + - `Optional ephemeral5mInputTokens` + + Tokens used to create 5-minute ephemeral cache entries. + + - `Optional cacheReadInputTokens` + + Total tokens read from prompt cache. + + - `Optional inputTokens` + + Total input tokens consumed across all turns. + + - `Optional outputTokens` + + Total output tokens generated across all turns. + + - `List vaultIds` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.sessions.BetaManagedAgentsSession; +import com.anthropic.models.beta.sessions.SessionUpdateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsSession betaManagedAgentsSession = client.beta().sessions().update("sesn_011CZkZAtmR3yMPDzynEDxu7"); + } +} +``` diff --git a/content/en/api/java/beta/skills.md b/content/en/api/java/beta/skills.md index 59730d398..283d3d244 100644 --- a/content/en/api/java/beta/skills.md +++ b/content/en/api/java/beta/skills.md @@ -58,8 +58,6 @@ Create Skill - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `Optional displayTitle` Display title for the skill. @@ -217,8 +215,6 @@ List Skills - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class SkillListResponse:` @@ -349,8 +345,6 @@ Get Skill - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class SkillRetrieveResponse:` @@ -481,8 +475,6 @@ Delete Skill - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class SkillDeleteResponse:` @@ -586,8 +578,6 @@ Create Skill Version - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `Optional> files` Files to upload for the skill. @@ -737,8 +727,6 @@ List Skill Versions - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class VersionListResponse:` @@ -878,8 +866,6 @@ Get Skill Version - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class VersionRetrieveResponse:` @@ -1023,8 +1009,6 @@ Delete Skill Version - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class VersionDeleteResponse:` diff --git a/content/en/api/java/beta/skills/create.md b/content/en/api/java/beta/skills/create.md index f552b64cb..d3950e166 100644 --- a/content/en/api/java/beta/skills/create.md +++ b/content/en/api/java/beta/skills/create.md @@ -56,8 +56,6 @@ Create Skill - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `Optional displayTitle` Display title for the skill. diff --git a/content/en/api/java/beta/skills/delete.md b/content/en/api/java/beta/skills/delete.md index 5e811d0f7..d78cd6d85 100644 --- a/content/en/api/java/beta/skills/delete.md +++ b/content/en/api/java/beta/skills/delete.md @@ -62,8 +62,6 @@ Delete Skill - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class SkillDeleteResponse:` diff --git a/content/en/api/java/beta/skills/list.md b/content/en/api/java/beta/skills/list.md index 9bb982240..20c53f2d2 100644 --- a/content/en/api/java/beta/skills/list.md +++ b/content/en/api/java/beta/skills/list.md @@ -77,8 +77,6 @@ List Skills - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class SkillListResponse:` diff --git a/content/en/api/java/beta/skills/retrieve.md b/content/en/api/java/beta/skills/retrieve.md index a18f09b5c..466f7125b 100644 --- a/content/en/api/java/beta/skills/retrieve.md +++ b/content/en/api/java/beta/skills/retrieve.md @@ -62,8 +62,6 @@ Get Skill - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class SkillRetrieveResponse:` diff --git a/content/en/api/java/beta/skills/versions.md b/content/en/api/java/beta/skills/versions.md index f45234940..f8d924efd 100644 --- a/content/en/api/java/beta/skills/versions.md +++ b/content/en/api/java/beta/skills/versions.md @@ -64,8 +64,6 @@ Create Skill Version - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `Optional> files` Files to upload for the skill. @@ -215,8 +213,6 @@ List Skill Versions - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class VersionListResponse:` @@ -356,8 +352,6 @@ Get Skill Version - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class VersionRetrieveResponse:` @@ -501,8 +495,6 @@ Delete Skill Version - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class VersionDeleteResponse:` diff --git a/content/en/api/java/beta/skills/versions/create.md b/content/en/api/java/beta/skills/versions/create.md index e15aadc33..d598b6762 100644 --- a/content/en/api/java/beta/skills/versions/create.md +++ b/content/en/api/java/beta/skills/versions/create.md @@ -62,8 +62,6 @@ Create Skill Version - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `Optional> files` Files to upload for the skill. diff --git a/content/en/api/java/beta/skills/versions/delete.md b/content/en/api/java/beta/skills/versions/delete.md index 07084e58a..9691e7fc2 100644 --- a/content/en/api/java/beta/skills/versions/delete.md +++ b/content/en/api/java/beta/skills/versions/delete.md @@ -68,8 +68,6 @@ Delete Skill Version - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class VersionDeleteResponse:` diff --git a/content/en/api/java/beta/skills/versions/list.md b/content/en/api/java/beta/skills/versions/list.md index 3eb9722d0..3f8c4b2b4 100644 --- a/content/en/api/java/beta/skills/versions/list.md +++ b/content/en/api/java/beta/skills/versions/list.md @@ -72,8 +72,6 @@ List Skill Versions - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class VersionListResponse:` diff --git a/content/en/api/java/beta/skills/versions/retrieve.md b/content/en/api/java/beta/skills/versions/retrieve.md index da3d7eaae..3d2c694f6 100644 --- a/content/en/api/java/beta/skills/versions/retrieve.md +++ b/content/en/api/java/beta/skills/versions/retrieve.md @@ -68,8 +68,6 @@ Get Skill Version - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class VersionRetrieveResponse:` diff --git a/content/en/api/java/beta/vaults.md b/content/en/api/java/beta/vaults.md new file mode 100644 index 000000000..58c620573 --- /dev/null +++ b/content/en/api/java/beta/vaults.md @@ -0,0 +1,2709 @@ +# Vaults + +## Create + +`BetaManagedAgentsVault beta().vaults().create(VaultCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `VaultCreateParams params` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `String displayName` + + Human-readable name for the vault. 1-255 characters. + + - `Optional metadata` + + Arbitrary key-value metadata to attach to the vault. + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `String id` + + Unique identifier for the vault. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String displayName` + + Human-readable name for the vault. + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the vault. + + - `Type type` + + - `VAULT("vault")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.BetaManagedAgentsVault; +import com.anthropic.models.beta.vaults.VaultCreateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + VaultCreateParams params = VaultCreateParams.builder() + .displayName("Example vault") + .build(); + BetaManagedAgentsVault betaManagedAgentsVault = client.beta().vaults().create(params); + } +} +``` + +## List + +`VaultListPage beta().vaults().list(VaultListParamsparams = VaultListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `VaultListParams params` + + - `Optional includeArchived` + + Whether to include archived vaults in the results. + + - `Optional limit` + + Maximum number of vaults to return per page. Defaults to 20, maximum 100. + + - `Optional page` + + Opaque pagination token from a previous `list_vaults` response. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `String id` + + Unique identifier for the vault. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String displayName` + + Human-readable name for the vault. + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the vault. + + - `Type type` + + - `VAULT("vault")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.VaultListPage; +import com.anthropic.models.beta.vaults.VaultListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + VaultListPage page = client.beta().vaults().list(); + } +} +``` + +## Retrieve + +`BetaManagedAgentsVault beta().vaults().retrieve(VaultRetrieveParamsparams = VaultRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `VaultRetrieveParams params` + + - `Optional vaultId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `String id` + + Unique identifier for the vault. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String displayName` + + Human-readable name for the vault. + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the vault. + + - `Type type` + + - `VAULT("vault")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.BetaManagedAgentsVault; +import com.anthropic.models.beta.vaults.VaultRetrieveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsVault betaManagedAgentsVault = client.beta().vaults().retrieve("vlt_011CZkZDLs7fYzm1hXNPeRjv"); + } +} +``` + +## Update + +`BetaManagedAgentsVault beta().vaults().update(VaultUpdateParamsparams = VaultUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `VaultUpdateParams params` + + - `Optional vaultId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Optional displayName` + + Updated human-readable name for the vault. 1-255 characters. + + - `Optional metadata` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `String id` + + Unique identifier for the vault. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String displayName` + + Human-readable name for the vault. + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the vault. + + - `Type type` + + - `VAULT("vault")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.BetaManagedAgentsVault; +import com.anthropic.models.beta.vaults.VaultUpdateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsVault betaManagedAgentsVault = client.beta().vaults().update("vlt_011CZkZDLs7fYzm1hXNPeRjv"); + } +} +``` + +## Delete + +`BetaManagedAgentsDeletedVault beta().vaults().delete(VaultDeleteParamsparams = VaultDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `VaultDeleteParams params` + + - `Optional vaultId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsDeletedVault:` + + Confirmation of a deleted vault. + + - `String id` + + Unique identifier of the deleted vault. + + - `Type type` + + - `VAULT_DELETED("vault_deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.BetaManagedAgentsDeletedVault; +import com.anthropic.models.beta.vaults.VaultDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsDeletedVault betaManagedAgentsDeletedVault = client.beta().vaults().delete("vlt_011CZkZDLs7fYzm1hXNPeRjv"); + } +} +``` + +## Archive + +`BetaManagedAgentsVault beta().vaults().archive(VaultArchiveParamsparams = VaultArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `VaultArchiveParams params` + + - `Optional vaultId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `String id` + + Unique identifier for the vault. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String displayName` + + Human-readable name for the vault. + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the vault. + + - `Type type` + + - `VAULT("vault")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.BetaManagedAgentsVault; +import com.anthropic.models.beta.vaults.VaultArchiveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsVault betaManagedAgentsVault = client.beta().vaults().archive("vlt_011CZkZDLs7fYzm1hXNPeRjv"); + } +} +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `class BetaManagedAgentsDeletedVault:` + + Confirmation of a deleted vault. + + - `String id` + + Unique identifier of the deleted vault. + + - `Type type` + + - `VAULT_DELETED("vault_deleted")` + +### Beta Managed Agents Vault + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `String id` + + Unique identifier for the vault. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String displayName` + + Human-readable name for the vault. + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the vault. + + - `Type type` + + - `VAULT("vault")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`BetaManagedAgentsCredential beta().vaults().credentials().create(CredentialCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `CredentialCreateParams params` + + - `Optional vaultId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Auth auth` + + Authentication details for creating a credential. + + - `class BetaManagedAgentsMcpOAuthCreateParams:` + + Parameters for creating an MCP OAuth credential. + + - `String accessToken` + + OAuth access token. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `String clientId` + + OAuth client ID. + + - `String refreshToken` + + OAuth refresh token. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams:` + + Parameters for creating a static bearer token credential. + + - `String token` + + Static bearer token value. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `Optional displayName` + + Human-readable name for the credential. Up to 255 characters. + + - `Optional metadata` + + Arbitrary key-value metadata to attach to the credential. + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsStaticBearerCreateParams; +import com.anthropic.models.beta.vaults.credentials.CredentialCreateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialCreateParams params = CredentialCreateParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .auth(BetaManagedAgentsStaticBearerCreateParams.builder() + .token("bearer_exampletoken") + .mcpServerUrl("https://example-server.modelcontextprotocol.io/sse") + .type(BetaManagedAgentsStaticBearerCreateParams.Type.STATIC_BEARER) + .build()) + .build(); + BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().create(params); + } +} +``` + +## List + +`CredentialListPage beta().vaults().credentials().list(CredentialListParamsparams = CredentialListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `CredentialListParams params` + + - `Optional vaultId` + + - `Optional includeArchived` + + Whether to include archived credentials in the results. + + - `Optional limit` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `Optional page` + + Opaque pagination token from a previous `list_credentials` response. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.CredentialListPage; +import com.anthropic.models.beta.vaults.credentials.CredentialListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialListPage page = client.beta().vaults().credentials().list("vlt_011CZkZDLs7fYzm1hXNPeRjv"); + } +} +``` + +## Retrieve + +`BetaManagedAgentsCredential beta().vaults().credentials().retrieve(CredentialRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `CredentialRetrieveParams params` + + - `String vaultId` + + - `Optional credentialId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential; +import com.anthropic.models.beta.vaults.credentials.CredentialRetrieveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialRetrieveParams params = CredentialRetrieveParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw") + .build(); + BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().retrieve(params); + } +} +``` + +## Update + +`BetaManagedAgentsCredential beta().vaults().credentials().update(CredentialUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `CredentialUpdateParams params` + + - `String vaultId` + + - `Optional credentialId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Optional auth` + + Updated authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthUpdateParams:` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional accessToken` + + Updated OAuth access token. + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + Parameters for updating OAuth refresh token configuration. + + - `Optional refreshToken` + + Updated OAuth refresh token. + + - `Optional scope` + + Updated OAuth scope for the refresh request. + + - `Optional tokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `Optional clientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional clientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams:` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `Optional token` + + Updated static bearer token value. + + - `Optional displayName` + + Updated human-readable name for the credential. 1-255 characters. + + - `Optional metadata` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential; +import com.anthropic.models.beta.vaults.credentials.CredentialUpdateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialUpdateParams params = CredentialUpdateParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw") + .build(); + BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().update(params); + } +} +``` + +## Delete + +`BetaManagedAgentsDeletedCredential beta().vaults().credentials().delete(CredentialDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `CredentialDeleteParams params` + + - `String vaultId` + + - `Optional credentialId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsDeletedCredential:` + + Confirmation of a deleted credential. + + - `String id` + + Unique identifier of the deleted credential. + + - `Type type` + + - `VAULT_CREDENTIAL_DELETED("vault_credential_deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsDeletedCredential; +import com.anthropic.models.beta.vaults.credentials.CredentialDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialDeleteParams params = CredentialDeleteParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw") + .build(); + BetaManagedAgentsDeletedCredential betaManagedAgentsDeletedCredential = client.beta().vaults().credentials().delete(params); + } +} +``` + +## Archive + +`BetaManagedAgentsCredential beta().vaults().credentials().archive(CredentialArchiveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `CredentialArchiveParams params` + + - `String vaultId` + + - `Optional credentialId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential; +import com.anthropic.models.beta.vaults.credentials.CredentialArchiveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialArchiveParams params = CredentialArchiveParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw") + .build(); + BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().archive(params); + } +} +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `class BetaManagedAgentsDeletedCredential:` + + Confirmation of a deleted credential. + + - `String id` + + Unique identifier of the deleted credential. + + - `Type type` + + - `VAULT_CREDENTIAL_DELETED("vault_credential_deleted")` + +### Beta Managed Agents MCP OAuth Auth Response + +- `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `class BetaManagedAgentsMcpOAuthCreateParams:` + + Parameters for creating an MCP OAuth credential. + + - `String accessToken` + + OAuth access token. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `String clientId` + + OAuth client ID. + + - `String refreshToken` + + OAuth refresh token. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `class BetaManagedAgentsMcpOAuthRefreshParams:` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `String clientId` + + OAuth client ID. + + - `String refreshToken` + + OAuth refresh token. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `class BetaManagedAgentsMcpOAuthRefreshResponse:` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `class BetaManagedAgentsMcpOAuthRefreshUpdateParams:` + + Parameters for updating OAuth refresh token configuration. + + - `Optional refreshToken` + + Updated OAuth refresh token. + + - `Optional scope` + + Updated OAuth scope for the refresh request. + + - `Optional tokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `Optional clientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional clientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `class BetaManagedAgentsMcpOAuthUpdateParams:` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional accessToken` + + Updated OAuth access token. + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + Parameters for updating OAuth refresh token configuration. + + - `Optional refreshToken` + + Updated OAuth refresh token. + + - `Optional scope` + + Updated OAuth scope for the refresh request. + + - `Optional tokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `Optional clientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional clientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + +### Beta Managed Agents Static Bearer Create Params + +- `class BetaManagedAgentsStaticBearerCreateParams:` + + Parameters for creating a static bearer token credential. + + - `String token` + + Static bearer token value. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + +### Beta Managed Agents Static Bearer Update Params + +- `class BetaManagedAgentsStaticBearerUpdateParams:` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `Optional token` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `Optional clientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional clientSecret` + + Updated OAuth client secret. diff --git a/content/en/api/java/beta/vaults/archive.md b/content/en/api/java/beta/vaults/archive.md new file mode 100644 index 000000000..57e345267 --- /dev/null +++ b/content/en/api/java/beta/vaults/archive.md @@ -0,0 +1,114 @@ +## Archive + +`BetaManagedAgentsVault beta().vaults().archive(VaultArchiveParamsparams = VaultArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `VaultArchiveParams params` + + - `Optional vaultId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `String id` + + Unique identifier for the vault. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String displayName` + + Human-readable name for the vault. + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the vault. + + - `Type type` + + - `VAULT("vault")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.BetaManagedAgentsVault; +import com.anthropic.models.beta.vaults.VaultArchiveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsVault betaManagedAgentsVault = client.beta().vaults().archive("vlt_011CZkZDLs7fYzm1hXNPeRjv"); + } +} +``` diff --git a/content/en/api/java/beta/vaults/create.md b/content/en/api/java/beta/vaults/create.md new file mode 100644 index 000000000..94a35dcb5 --- /dev/null +++ b/content/en/api/java/beta/vaults/create.md @@ -0,0 +1,123 @@ +## Create + +`BetaManagedAgentsVault beta().vaults().create(VaultCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `VaultCreateParams params` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `String displayName` + + Human-readable name for the vault. 1-255 characters. + + - `Optional metadata` + + Arbitrary key-value metadata to attach to the vault. + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `String id` + + Unique identifier for the vault. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String displayName` + + Human-readable name for the vault. + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the vault. + + - `Type type` + + - `VAULT("vault")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.BetaManagedAgentsVault; +import com.anthropic.models.beta.vaults.VaultCreateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + VaultCreateParams params = VaultCreateParams.builder() + .displayName("Example vault") + .build(); + BetaManagedAgentsVault betaManagedAgentsVault = client.beta().vaults().create(params); + } +} +``` diff --git a/content/en/api/java/beta/vaults/credentials.md b/content/en/api/java/beta/vaults/credentials.md new file mode 100644 index 000000000..5bf1ee7bb --- /dev/null +++ b/content/en/api/java/beta/vaults/credentials.md @@ -0,0 +1,1960 @@ +# Credentials + +## Create + +`BetaManagedAgentsCredential beta().vaults().credentials().create(CredentialCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `CredentialCreateParams params` + + - `Optional vaultId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Auth auth` + + Authentication details for creating a credential. + + - `class BetaManagedAgentsMcpOAuthCreateParams:` + + Parameters for creating an MCP OAuth credential. + + - `String accessToken` + + OAuth access token. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `String clientId` + + OAuth client ID. + + - `String refreshToken` + + OAuth refresh token. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams:` + + Parameters for creating a static bearer token credential. + + - `String token` + + Static bearer token value. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `Optional displayName` + + Human-readable name for the credential. Up to 255 characters. + + - `Optional metadata` + + Arbitrary key-value metadata to attach to the credential. + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsStaticBearerCreateParams; +import com.anthropic.models.beta.vaults.credentials.CredentialCreateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialCreateParams params = CredentialCreateParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .auth(BetaManagedAgentsStaticBearerCreateParams.builder() + .token("bearer_exampletoken") + .mcpServerUrl("https://example-server.modelcontextprotocol.io/sse") + .type(BetaManagedAgentsStaticBearerCreateParams.Type.STATIC_BEARER) + .build()) + .build(); + BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().create(params); + } +} +``` + +## List + +`CredentialListPage beta().vaults().credentials().list(CredentialListParamsparams = CredentialListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `CredentialListParams params` + + - `Optional vaultId` + + - `Optional includeArchived` + + Whether to include archived credentials in the results. + + - `Optional limit` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `Optional page` + + Opaque pagination token from a previous `list_credentials` response. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.CredentialListPage; +import com.anthropic.models.beta.vaults.credentials.CredentialListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialListPage page = client.beta().vaults().credentials().list("vlt_011CZkZDLs7fYzm1hXNPeRjv"); + } +} +``` + +## Retrieve + +`BetaManagedAgentsCredential beta().vaults().credentials().retrieve(CredentialRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `CredentialRetrieveParams params` + + - `String vaultId` + + - `Optional credentialId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential; +import com.anthropic.models.beta.vaults.credentials.CredentialRetrieveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialRetrieveParams params = CredentialRetrieveParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw") + .build(); + BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().retrieve(params); + } +} +``` + +## Update + +`BetaManagedAgentsCredential beta().vaults().credentials().update(CredentialUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `CredentialUpdateParams params` + + - `String vaultId` + + - `Optional credentialId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Optional auth` + + Updated authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthUpdateParams:` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional accessToken` + + Updated OAuth access token. + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + Parameters for updating OAuth refresh token configuration. + + - `Optional refreshToken` + + Updated OAuth refresh token. + + - `Optional scope` + + Updated OAuth scope for the refresh request. + + - `Optional tokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `Optional clientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional clientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams:` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `Optional token` + + Updated static bearer token value. + + - `Optional displayName` + + Updated human-readable name for the credential. 1-255 characters. + + - `Optional metadata` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential; +import com.anthropic.models.beta.vaults.credentials.CredentialUpdateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialUpdateParams params = CredentialUpdateParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw") + .build(); + BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().update(params); + } +} +``` + +## Delete + +`BetaManagedAgentsDeletedCredential beta().vaults().credentials().delete(CredentialDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `CredentialDeleteParams params` + + - `String vaultId` + + - `Optional credentialId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsDeletedCredential:` + + Confirmation of a deleted credential. + + - `String id` + + Unique identifier of the deleted credential. + + - `Type type` + + - `VAULT_CREDENTIAL_DELETED("vault_credential_deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsDeletedCredential; +import com.anthropic.models.beta.vaults.credentials.CredentialDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialDeleteParams params = CredentialDeleteParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw") + .build(); + BetaManagedAgentsDeletedCredential betaManagedAgentsDeletedCredential = client.beta().vaults().credentials().delete(params); + } +} +``` + +## Archive + +`BetaManagedAgentsCredential beta().vaults().credentials().archive(CredentialArchiveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `CredentialArchiveParams params` + + - `String vaultId` + + - `Optional credentialId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential; +import com.anthropic.models.beta.vaults.credentials.CredentialArchiveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialArchiveParams params = CredentialArchiveParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw") + .build(); + BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().archive(params); + } +} +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `class BetaManagedAgentsDeletedCredential:` + + Confirmation of a deleted credential. + + - `String id` + + Unique identifier of the deleted credential. + + - `Type type` + + - `VAULT_CREDENTIAL_DELETED("vault_credential_deleted")` + +### Beta Managed Agents MCP OAuth Auth Response + +- `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `class BetaManagedAgentsMcpOAuthCreateParams:` + + Parameters for creating an MCP OAuth credential. + + - `String accessToken` + + OAuth access token. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `String clientId` + + OAuth client ID. + + - `String refreshToken` + + OAuth refresh token. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `class BetaManagedAgentsMcpOAuthRefreshParams:` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `String clientId` + + OAuth client ID. + + - `String refreshToken` + + OAuth refresh token. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `class BetaManagedAgentsMcpOAuthRefreshResponse:` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `class BetaManagedAgentsMcpOAuthRefreshUpdateParams:` + + Parameters for updating OAuth refresh token configuration. + + - `Optional refreshToken` + + Updated OAuth refresh token. + + - `Optional scope` + + Updated OAuth scope for the refresh request. + + - `Optional tokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `Optional clientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional clientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `class BetaManagedAgentsMcpOAuthUpdateParams:` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional accessToken` + + Updated OAuth access token. + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + Parameters for updating OAuth refresh token configuration. + + - `Optional refreshToken` + + Updated OAuth refresh token. + + - `Optional scope` + + Updated OAuth scope for the refresh request. + + - `Optional tokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `Optional clientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional clientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + +### Beta Managed Agents Static Bearer Create Params + +- `class BetaManagedAgentsStaticBearerCreateParams:` + + Parameters for creating a static bearer token credential. + + - `String token` + + Static bearer token value. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + +### Beta Managed Agents Static Bearer Update Params + +- `class BetaManagedAgentsStaticBearerUpdateParams:` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `Optional token` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `Optional clientSecret` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional clientSecret` + + Updated OAuth client secret. diff --git a/content/en/api/java/beta/vaults/credentials/archive.md b/content/en/api/java/beta/vaults/credentials/archive.md new file mode 100644 index 000000000..733f5f8f1 --- /dev/null +++ b/content/en/api/java/beta/vaults/credentials/archive.md @@ -0,0 +1,204 @@ +## Archive + +`BetaManagedAgentsCredential beta().vaults().credentials().archive(CredentialArchiveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `CredentialArchiveParams params` + + - `String vaultId` + + - `Optional credentialId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential; +import com.anthropic.models.beta.vaults.credentials.CredentialArchiveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialArchiveParams params = CredentialArchiveParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw") + .build(); + BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().archive(params); + } +} +``` diff --git a/content/en/api/java/beta/vaults/credentials/create.md b/content/en/api/java/beta/vaults/credentials/create.md new file mode 100644 index 000000000..09e2cd2bf --- /dev/null +++ b/content/en/api/java/beta/vaults/credentials/create.md @@ -0,0 +1,315 @@ +## Create + +`BetaManagedAgentsCredential beta().vaults().credentials().create(CredentialCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `CredentialCreateParams params` + + - `Optional vaultId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Auth auth` + + Authentication details for creating a credential. + + - `class BetaManagedAgentsMcpOAuthCreateParams:` + + Parameters for creating an MCP OAuth credential. + + - `String accessToken` + + OAuth access token. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `String clientId` + + OAuth client ID. + + - `String refreshToken` + + OAuth refresh token. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam:` + + Token endpoint uses POST body authentication with client credentials. + + - `String clientSecret` + + OAuth client secret. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams:` + + Parameters for creating a static bearer token credential. + + - `String token` + + Static bearer token value. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `Optional displayName` + + Human-readable name for the credential. Up to 255 characters. + + - `Optional metadata` + + Arbitrary key-value metadata to attach to the credential. + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsStaticBearerCreateParams; +import com.anthropic.models.beta.vaults.credentials.CredentialCreateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialCreateParams params = CredentialCreateParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .auth(BetaManagedAgentsStaticBearerCreateParams.builder() + .token("bearer_exampletoken") + .mcpServerUrl("https://example-server.modelcontextprotocol.io/sse") + .type(BetaManagedAgentsStaticBearerCreateParams.Type.STATIC_BEARER) + .build()) + .build(); + BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().create(params); + } +} +``` diff --git a/content/en/api/java/beta/vaults/credentials/delete.md b/content/en/api/java/beta/vaults/credentials/delete.md new file mode 100644 index 000000000..ecea986a3 --- /dev/null +++ b/content/en/api/java/beta/vaults/credentials/delete.md @@ -0,0 +1,100 @@ +## Delete + +`BetaManagedAgentsDeletedCredential beta().vaults().credentials().delete(CredentialDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `CredentialDeleteParams params` + + - `String vaultId` + + - `Optional credentialId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsDeletedCredential:` + + Confirmation of a deleted credential. + + - `String id` + + Unique identifier of the deleted credential. + + - `Type type` + + - `VAULT_CREDENTIAL_DELETED("vault_credential_deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsDeletedCredential; +import com.anthropic.models.beta.vaults.credentials.CredentialDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialDeleteParams params = CredentialDeleteParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw") + .build(); + BetaManagedAgentsDeletedCredential betaManagedAgentsDeletedCredential = client.beta().vaults().credentials().delete(params); + } +} +``` diff --git a/content/en/api/java/beta/vaults/credentials/list.md b/content/en/api/java/beta/vaults/credentials/list.md new file mode 100644 index 000000000..9f0909ccd --- /dev/null +++ b/content/en/api/java/beta/vaults/credentials/list.md @@ -0,0 +1,210 @@ +## List + +`CredentialListPage beta().vaults().credentials().list(CredentialListParamsparams = CredentialListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `CredentialListParams params` + + - `Optional vaultId` + + - `Optional includeArchived` + + Whether to include archived credentials in the results. + + - `Optional limit` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `Optional page` + + Opaque pagination token from a previous `list_credentials` response. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.CredentialListPage; +import com.anthropic.models.beta.vaults.credentials.CredentialListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialListPage page = client.beta().vaults().credentials().list("vlt_011CZkZDLs7fYzm1hXNPeRjv"); + } +} +``` diff --git a/content/en/api/java/beta/vaults/credentials/retrieve.md b/content/en/api/java/beta/vaults/credentials/retrieve.md new file mode 100644 index 000000000..8616181eb --- /dev/null +++ b/content/en/api/java/beta/vaults/credentials/retrieve.md @@ -0,0 +1,204 @@ +## Retrieve + +`BetaManagedAgentsCredential beta().vaults().credentials().retrieve(CredentialRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `CredentialRetrieveParams params` + + - `String vaultId` + + - `Optional credentialId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential; +import com.anthropic.models.beta.vaults.credentials.CredentialRetrieveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialRetrieveParams params = CredentialRetrieveParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw") + .build(); + BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().retrieve(params); + } +} +``` diff --git a/content/en/api/java/beta/vaults/credentials/update.md b/content/en/api/java/beta/vaults/credentials/update.md new file mode 100644 index 000000000..997ef7b16 --- /dev/null +++ b/content/en/api/java/beta/vaults/credentials/update.md @@ -0,0 +1,284 @@ +## Update + +`BetaManagedAgentsCredential beta().vaults().credentials().update(CredentialUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `CredentialUpdateParams params` + + - `String vaultId` + + - `Optional credentialId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Optional auth` + + Updated authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthUpdateParams:` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional accessToken` + + Updated OAuth access token. + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + Parameters for updating OAuth refresh token configuration. + + - `Optional refreshToken` + + Updated OAuth refresh token. + + - `Optional scope` + + Updated OAuth scope for the refresh request. + + - `Optional tokenEndpointAuth` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `Optional clientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:` + + Updated POST body authentication parameters for the token endpoint. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional clientSecret` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams:` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `Optional token` + + Updated static bearer token value. + + - `Optional displayName` + + Updated human-readable name for the credential. 1-255 characters. + + - `Optional metadata` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +### Returns + +- `class BetaManagedAgentsCredential:` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `String id` + + Unique identifier for the credential. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `Auth auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMcpOAuthAuthResponse:` + + OAuth credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `MCP_OAUTH("mcp_oauth")` + + - `Optional expiresAt` + + A timestamp in RFC 3339 format + + - `Optional refresh` + + OAuth refresh token configuration returned in credential responses. + + - `String clientId` + + OAuth client ID. + + - `String tokenEndpoint` + + Token endpoint URL used to refresh the access token. + + - `TokenEndpointAuth tokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:` + + Token endpoint requires no client authentication. + + - `Type type` + + - `NONE("none")` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_BASIC("client_secret_basic")` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse:` + + Token endpoint uses POST body authentication with client credentials. + + - `Type type` + + - `CLIENT_SECRET_POST("client_secret_post")` + + - `Optional resource` + + OAuth resource indicator. + + - `Optional scope` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse:` + + Static bearer token credential details for an MCP server. + + - `String mcpServerUrl` + + URL of the MCP server this credential authenticates against. + + - `Type type` + + - `STATIC_BEARER("static_bearer")` + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the credential. + + - `Type type` + + - `VAULT_CREDENTIAL("vault_credential")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + + - `String vaultId` + + Identifier of the vault this credential belongs to. + + - `Optional displayName` + + Human-readable name for the credential. + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential; +import com.anthropic.models.beta.vaults.credentials.CredentialUpdateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + CredentialUpdateParams params = CredentialUpdateParams.builder() + .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv") + .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw") + .build(); + BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().update(params); + } +} +``` diff --git a/content/en/api/java/beta/vaults/delete.md b/content/en/api/java/beta/vaults/delete.md new file mode 100644 index 000000000..e5ff3bfad --- /dev/null +++ b/content/en/api/java/beta/vaults/delete.md @@ -0,0 +1,94 @@ +## Delete + +`BetaManagedAgentsDeletedVault beta().vaults().delete(VaultDeleteParamsparams = VaultDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `VaultDeleteParams params` + + - `Optional vaultId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsDeletedVault:` + + Confirmation of a deleted vault. + + - `String id` + + Unique identifier of the deleted vault. + + - `Type type` + + - `VAULT_DELETED("vault_deleted")` + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.BetaManagedAgentsDeletedVault; +import com.anthropic.models.beta.vaults.VaultDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsDeletedVault betaManagedAgentsDeletedVault = client.beta().vaults().delete("vlt_011CZkZDLs7fYzm1hXNPeRjv"); + } +} +``` diff --git a/content/en/api/java/beta/vaults/list.md b/content/en/api/java/beta/vaults/list.md new file mode 100644 index 000000000..258392f56 --- /dev/null +++ b/content/en/api/java/beta/vaults/list.md @@ -0,0 +1,124 @@ +## List + +`VaultListPage beta().vaults().list(VaultListParamsparams = VaultListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `VaultListParams params` + + - `Optional includeArchived` + + Whether to include archived vaults in the results. + + - `Optional limit` + + Maximum number of vaults to return per page. Defaults to 20, maximum 100. + + - `Optional page` + + Opaque pagination token from a previous `list_vaults` response. + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `String id` + + Unique identifier for the vault. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String displayName` + + Human-readable name for the vault. + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the vault. + + - `Type type` + + - `VAULT("vault")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.VaultListPage; +import com.anthropic.models.beta.vaults.VaultListParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + VaultListPage page = client.beta().vaults().list(); + } +} +``` diff --git a/content/en/api/java/beta/vaults/retrieve.md b/content/en/api/java/beta/vaults/retrieve.md new file mode 100644 index 000000000..2214541dc --- /dev/null +++ b/content/en/api/java/beta/vaults/retrieve.md @@ -0,0 +1,114 @@ +## Retrieve + +`BetaManagedAgentsVault beta().vaults().retrieve(VaultRetrieveParamsparams = VaultRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `VaultRetrieveParams params` + + - `Optional vaultId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `String id` + + Unique identifier for the vault. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String displayName` + + Human-readable name for the vault. + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the vault. + + - `Type type` + + - `VAULT("vault")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.BetaManagedAgentsVault; +import com.anthropic.models.beta.vaults.VaultRetrieveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsVault betaManagedAgentsVault = client.beta().vaults().retrieve("vlt_011CZkZDLs7fYzm1hXNPeRjv"); + } +} +``` diff --git a/content/en/api/java/beta/vaults/update.md b/content/en/api/java/beta/vaults/update.md new file mode 100644 index 000000000..ccaea68bf --- /dev/null +++ b/content/en/api/java/beta/vaults/update.md @@ -0,0 +1,122 @@ +## Update + +`BetaManagedAgentsVault beta().vaults().update(VaultUpdateParamsparams = VaultUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `VaultUpdateParams params` + + - `Optional vaultId` + + - `Optional> betas` + + Optional header to specify the beta version(s) you want to use. + + - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")` + + - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")` + + - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")` + + - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")` + + - `PDFS_2024_09_25("pdfs-2024-09-25")` + + - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")` + + - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")` + + - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")` + + - `FILES_API_2025_04_14("files-api-2025-04-14")` + + - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")` + + - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")` + + - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")` + + - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")` + + - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")` + + - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")` + + - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")` + + - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")` + + - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")` + + - `SKILLS_2025_10_02("skills-2025-10-02")` + + - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")` + + - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` + + - `Optional displayName` + + Updated human-readable name for the vault. 1-255 characters. + + - `Optional metadata` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +### Returns + +- `class BetaManagedAgentsVault:` + + A vault that stores credentials for use by agents during sessions. + + - `String id` + + Unique identifier for the vault. + + - `Optional archivedAt` + + A timestamp in RFC 3339 format + + - `LocalDateTime createdAt` + + A timestamp in RFC 3339 format + + - `String displayName` + + Human-readable name for the vault. + + - `Metadata metadata` + + Arbitrary key-value metadata attached to the vault. + + - `Type type` + + - `VAULT("vault")` + + - `LocalDateTime updatedAt` + + A timestamp in RFC 3339 format + +### Example + +```java +package com.anthropic.example; + +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.beta.vaults.BetaManagedAgentsVault; +import com.anthropic.models.beta.vaults.VaultUpdateParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + BetaManagedAgentsVault betaManagedAgentsVault = client.beta().vaults().update("vlt_011CZkZDLs7fYzm1hXNPeRjv"); + } +} +``` diff --git a/content/en/api/java/completions.md b/content/en/api/java/completions.md index 913221e75..1ae75e2d7 100644 --- a/content/en/api/java/completions.md +++ b/content/en/api/java/completions.md @@ -62,8 +62,6 @@ Future models and features will not be compatible with Text Completions. See our - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `long maxTokensToSample` The maximum number of tokens to generate before stopping. @@ -152,9 +150,13 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -248,7 +250,7 @@ public final class Main { CompletionCreateParams params = CompletionCreateParams.builder() .maxTokensToSample(256L) - .model(Model.CLAUDE_OPUS_4_6) + .model(Model.CLAUDE_MYTHOS_PREVIEW) .prompt("\n\nHuman: Hello, world!\n\nAssistant:") .build(); Completion completion = client.completions().create(params); @@ -278,9 +280,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` diff --git a/content/en/api/java/completions/create.md b/content/en/api/java/completions/create.md index b49aebd23..7b1b109e7 100644 --- a/content/en/api/java/completions/create.md +++ b/content/en/api/java/completions/create.md @@ -60,8 +60,6 @@ Future models and features will not be compatible with Text Completions. See our - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - - `long maxTokensToSample` The maximum number of tokens to generate before stopping. @@ -150,9 +148,13 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -246,7 +248,7 @@ public final class Main { CompletionCreateParams params = CompletionCreateParams.builder() .maxTokensToSample(256L) - .model(Model.CLAUDE_OPUS_4_6) + .model(Model.CLAUDE_MYTHOS_PREVIEW) .prompt("\n\nHuman: Hello, world!\n\nAssistant:") .build(); Completion completion = client.completions().create(params); diff --git a/content/en/api/java/messages.md b/content/en/api/java/messages.md index 1408ca041..01076eb40 100644 --- a/content/en/api/java/messages.md +++ b/content/en/api/java/messages.md @@ -4315,9 +4315,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -13805,9 +13809,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -19133,9 +19141,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -20061,9 +20073,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -29150,9 +29166,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -31985,9 +32005,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -33255,9 +33279,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -34311,9 +34339,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -35329,9 +35361,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` diff --git a/content/en/api/java/messages/batches.md b/content/en/api/java/messages/batches.md index 7515cc09c..759a28deb 100644 --- a/content/en/api/java/messages/batches.md +++ b/content/en/api/java/messages/batches.md @@ -2323,9 +2323,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -5158,9 +5162,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -6428,9 +6436,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -7484,9 +7496,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` @@ -8502,9 +8518,13 @@ public final class Main { See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` diff --git a/content/en/api/java/messages/batches/create.md b/content/en/api/java/messages/batches/create.md index 0acabe70e..ba898e552 100644 --- a/content/en/api/java/messages/batches/create.md +++ b/content/en/api/java/messages/batches/create.md @@ -2321,9 +2321,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` diff --git a/content/en/api/java/messages/batches/results.md b/content/en/api/java/messages/batches/results.md index 2da46ca61..e74be47e1 100644 --- a/content/en/api/java/messages/batches/results.md +++ b/content/en/api/java/messages/batches/results.md @@ -749,9 +749,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` diff --git a/content/en/api/java/messages/create.md b/content/en/api/java/messages/create.md index a6516ff83..ded5e360e 100644 --- a/content/en/api/java/messages/create.md +++ b/content/en/api/java/messages/create.md @@ -4313,9 +4313,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")` + + New class of intelligence, strongest in coding and cybersecurity + - `CLAUDE_OPUS_4_6("claude-opus-4-6")` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")` diff --git a/content/en/api/java/models.md b/content/en/api/java/models.md index 6c5304e02..5ebc1ac0a 100644 --- a/content/en/api/java/models.md +++ b/content/en/api/java/models.md @@ -74,8 +74,6 @@ The Models API response can be used to determine which models are available for - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class ModelInfo:` @@ -345,8 +343,6 @@ The Models API response can be used to determine information about a specific mo - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class ModelInfo:` diff --git a/content/en/api/java/models/list.md b/content/en/api/java/models/list.md index 60c07fc8c..7d22c21ef 100644 --- a/content/en/api/java/models/list.md +++ b/content/en/api/java/models/list.md @@ -72,8 +72,6 @@ The Models API response can be used to determine which models are available for - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class ModelInfo:` diff --git a/content/en/api/java/models/retrieve.md b/content/en/api/java/models/retrieve.md index 19cfb7e03..4ffb5b7b5 100644 --- a/content/en/api/java/models/retrieve.md +++ b/content/en/api/java/models/retrieve.md @@ -62,8 +62,6 @@ The Models API response can be used to determine information about a specific mo - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")` - - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")` - ### Returns - `class ModelInfo:` diff --git a/content/en/api/messages.md b/content/en/api/messages.md index c26e42149..cefeab18e 100644 --- a/content/en/api/messages.md +++ b/content/en/api/messages.md @@ -2303,15 +2303,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4530,15 +4534,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -7052,15 +7060,19 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -8522,7 +8534,7 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ "role": "user" } ], - "model": "claude-opus-4-6" + "model": "claude-mythos-preview" }' ``` @@ -14216,15 +14228,19 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -17747,21 +17763,25 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ ### Model -- `Model = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more or string` +- `Model = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -19628,15 +19648,19 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -20564,15 +20588,19 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -29657,15 +29685,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -32436,15 +32468,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -33700,15 +33736,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -34764,15 +34804,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -35790,15 +35834,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/messages/batches.md b/content/en/api/messages/batches.md index 80b31374b..74c3aabeb 100644 --- a/content/en/api/messages/batches.md +++ b/content/en/api/messages/batches.md @@ -2319,15 +2319,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -5098,15 +5102,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -6362,15 +6370,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -7426,15 +7438,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -8452,15 +8468,19 @@ curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \ See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/messages/batches/create.md b/content/en/api/messages/batches/create.md index 922740e31..fa9394d8f 100644 --- a/content/en/api/messages/batches/create.md +++ b/content/en/api/messages/batches/create.md @@ -2317,15 +2317,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/messages/batches/results.md b/content/en/api/messages/batches/results.md index dfa847144..34625b23a 100644 --- a/content/en/api/messages/batches/results.md +++ b/content/en/api/messages/batches/results.md @@ -745,15 +745,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/messages/count_tokens.md b/content/en/api/messages/count_tokens.md index c0a233fd2..6af97ef62 100644 --- a/content/en/api/messages/count_tokens.md +++ b/content/en/api/messages/count_tokens.md @@ -2293,15 +2293,19 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -3763,6 +3767,6 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ "role": "user" } ], - "model": "claude-opus-4-6" + "model": "claude-mythos-preview" }' ``` diff --git a/content/en/api/messages/create.md b/content/en/api/messages/create.md index 1dcad7039..42d4f2b41 100644 --- a/content/en/api/messages/create.md +++ b/content/en/api/messages/create.md @@ -2301,15 +2301,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4528,15 +4532,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-haiku-4-5" or 12 more` + - `UnionMember0 = "claude-mythos-preview" or "claude-opus-4-6" or "claude-sonnet-4-6" or 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/models.md b/content/en/api/models.md index a5459f9fe..1c0cc11b2 100644 --- a/content/en/api/models.md +++ b/content/en/api/models.md @@ -32,7 +32,7 @@ The Models API response can be used to determine which models are available for - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -76,8 +76,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of ModelInfo` @@ -304,7 +302,7 @@ The Models API response can be used to determine information about a specific mo - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -348,8 +346,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `ModelInfo = object { id, capabilities, created_at, 4 more }` diff --git a/content/en/api/models/list.md b/content/en/api/models/list.md index def238a7b..413a21e75 100644 --- a/content/en/api/models/list.md +++ b/content/en/api/models/list.md @@ -30,7 +30,7 @@ The Models API response can be used to determine which models are available for - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `data: array of ModelInfo` diff --git a/content/en/api/models/retrieve.md b/content/en/api/models/retrieve.md index f1f9ec547..de0c82227 100644 --- a/content/en/api/models/retrieve.md +++ b/content/en/api/models/retrieve.md @@ -20,7 +20,7 @@ The Models API response can be used to determine information about a specific mo - `UnionMember0 = string` - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 19 more` + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 18 more` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `ModelInfo = object { id, capabilities, created_at, 4 more }` diff --git a/content/en/api/overview.md b/content/en/api/overview.md index 9b3e66d98..b261e4bd9 100644 --- a/content/en/api/overview.md +++ b/content/en/api/overview.md @@ -2,17 +2,17 @@ --- -The Claude API is a RESTful API at `https://api.anthropic.com` that provides programmatic access to Claude models. The primary API is the Messages API (`POST /v1/messages`) for conversational interactions. +The Claude API is a RESTful API at `https://api.anthropic.com` that provides programmatic access to Claude models and Claude Managed Agents. -**New to Claude?** Start with [Get started](/docs/en/get-started) for prerequisites and your first API call, or see [Working with Messages](/docs/en/build-with-claude/working-with-messages) for request/response patterns and examples. +**New to Claude?** For direct model access, start with [Get started](/docs/en/get-started) and [Working with Messages](/docs/en/build-with-claude/working-with-messages). For managed agent infrastructure, see the [Claude Managed Agents quickstart](/docs/en/managed-agents/quickstart). ## Prerequisites To use the Claude API, you'll need: -- An [Anthropic Console account](https://platform.claude.com) +- A [Claude Console account](https://platform.claude.com) - An [API key](/settings/keys) For step-by-step setup instructions, see [Get started](/docs/en/get-started). @@ -22,7 +22,7 @@ For step-by-step setup instructions, see [Get started](/docs/en/get-started). The Claude API includes the following APIs: **General Availability:** -- **[Messages API](/docs/en/api/messages)**: Send messages to Claude for conversational interactions (`POST /v1/messages`) +- **[Messages API](/docs/en/api/messages/create)**: Send messages to Claude for conversational interactions (`POST /v1/messages`) - **[Message Batches API](/docs/en/api/creating-message-batches)**: Process large volumes of Messages requests asynchronously with 50% cost reduction (`POST /v1/messages/batches`) - **[Token Counting API](/docs/en/api/messages-count-tokens)**: Count tokens in a message before sending to manage costs and rate limits (`POST /v1/messages/count_tokens`) - **[Models API](/docs/en/api/models-list)**: List available Claude models and their details (`GET /v1/models`) @@ -30,11 +30,12 @@ The Claude API includes the following APIs: **Beta:** - **[Files API](/docs/en/api/files-create)**: Upload and manage files for use across multiple API calls (`POST /v1/files`, `GET /v1/files`) - **[Skills API](/docs/en/api/skills/create-skill)**: Create and manage custom agent skills (`POST /v1/skills`, `GET /v1/skills`) +- **[Agents API](/docs/en/api/beta/agents/create)**: Define reusable, versioned agent configurations for Claude Managed Agents (`POST /v1/agents`, `GET /v1/agents`) +- **[Sessions API](/docs/en/api/beta/sessions/create)**: Run stateful agent sessions in managed cloud containers (`POST /v1/sessions`, `GET /v1/sessions/{id}/stream`) +- **[Environments API](/docs/en/api/beta/environments/create)**: Configure container templates for agent sessions (`POST /v1/environments`, `GET /v1/environments`) For the complete API reference with all endpoints, parameters, and response schemas, explore the API reference pages listed in the navigation. To access beta features, see [Beta headers](/docs/en/api/beta-headers). -The Messages API supports an optional `inference_geo` parameter for [data residency controls](/docs/en/build-with-claude/data-residency), allowing you to specify where model inference runs. - ## Authentication All requests to the Claude API must include these headers: @@ -62,23 +63,11 @@ Anthropic provides official SDKs that simplify API integration by handling authe - Streaming support - Request timeouts and connection management -**Example** (Python): -```python -from anthropic import Anthropic - -client = Anthropic() # Reads ANTHROPIC_API_KEY from environment -message = client.messages.create( - model="claude-opus-4-6", - max_tokens=1024, - messages=[{"role": "user", "content": "Hello, Claude"}], -) -``` - For a list of client SDKs and their respective installation instructions, see [Client SDKs](/docs/en/api/client-sdks). -## Claude API vs Third-Party Platforms +## Availability on partner platforms -Claude is available through Anthropic's direct API and through partner platforms. Choose based on your infrastructure, compliance requirements, and pricing preferences. +Claude is available through the direct Claude API and through partner platforms. Choose based on your infrastructure, compliance requirements, and pricing preferences. ### Claude API @@ -100,20 +89,19 @@ Access Claude through AWS, Google Cloud, or Microsoft Azure: | Azure AI | Microsoft Azure | [Claude on Azure AI](/docs/en/build-with-claude/claude-in-microsoft-foundry) | -For feature availability across platforms, see the [Features overview](/docs/en/build-with-claude/overview). +Claude Managed Agents is available only through the direct Claude API. For feature availability across platforms, see the [Features overview](/docs/en/build-with-claude/overview). ## Request and Response Format -### Request Size Limits - -The API has different maximum request sizes depending on the endpoint: +### Request size limits -| Endpoint | Maximum Size | -|----------|--------------| -| Standard endpoints (Messages, Token Counting) | 32 MB | +| Endpoint | Maximum request size | +| --- | --- | +| Messages, Token Counting | 32 MB | | [Batch API](/docs/en/build-with-claude/batch-processing) | 256 MB | | [Files API](/docs/en/build-with-claude/files) | 500 MB | +| Sessions, Agents, Environments | 32 MB | If you exceed these limits, you'll receive a 413 `request_too_large` error. @@ -145,66 +133,19 @@ For detailed information about limits, tiers, and the token bucket algorithm use The Claude API is available in [many countries and regions](/docs/en/api/supported-regions) worldwide. Check the supported regions page to confirm availability in your location. -## Basic Example - -Here's a minimal request using the Messages API: - -```bash -curl https://api.anthropic.com/v1/messages \ - --header "x-api-key: $ANTHROPIC_API_KEY" \ - --header "anthropic-version: 2023-06-01" \ - --header "content-type: application/json" \ - --data '{ - "model": "claude-opus-4-6", - "max_tokens": 1024, - "messages": [ - {"role": "user", "content": "Hello, Claude"} - ] - }' -``` - -**Response:** -```json -{ - "id": "msg_01XFDUDYJgAACzvnptvVoYEL", - "type": "message", - "role": "assistant", - "content": [ - { - "type": "text", - "text": "Hello! How can I assist you today?" - } - ], - "model": "claude-opus-4-6", - "stop_reason": "end_turn", - "usage": { - "input_tokens": 12, - "output_tokens": 8 - } -} -``` - -For complete examples and tutorials, see [Get started](/docs/en/get-started) and [Working with Messages](/docs/en/build-with-claude/working-with-messages). - ## Next Steps - - - Prerequisites, step-by-step tutorial, and examples in multiple languages - - - Request/response patterns, multi-turn conversations, and best practices + + + Complete API specification for direct model interactions - - Complete API specification: parameters, responses, and error codes + + Agents, Sessions, and Environments endpoints - Installation guides for Python, TypeScript, Java, Go, C#, Ruby, and PHP - - - Explore capabilities: caching, vision, tool use, streaming, and more + Python, TypeScript, Java, Go, C#, Ruby, and PHP - Usage tiers, spend limits, and rate limiting with token bucket algorithm + Usage tiers, spend limits, and token bucket algorithm \ No newline at end of file diff --git a/content/en/api/php/beta.md b/content/en/api/php/beta.md index 0f1c2f42e..d8351ffd3 100644 --- a/content/en/api/php/beta.md +++ b/content/en/api/php/beta.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                        \ No newline at end of file diff --git a/content/en/api/php/beta/agents.md b/content/en/api/php/beta/agents.md new file mode 100644 index 000000000..77f35762d --- /dev/null +++ b/content/en/api/php/beta/agents.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                          \ No newline at end of file diff --git a/content/en/api/php/beta/agents/archive.md b/content/en/api/php/beta/agents/archive.md new file mode 100644 index 000000000..89b9eb923 --- /dev/null +++ b/content/en/api/php/beta/agents/archive.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                            \ No newline at end of file diff --git a/content/en/api/php/beta/agents/create.md b/content/en/api/php/beta/agents/create.md new file mode 100644 index 000000000..a27c111b7 --- /dev/null +++ b/content/en/api/php/beta/agents/create.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                              \ No newline at end of file diff --git a/content/en/api/php/beta/agents/list.md b/content/en/api/php/beta/agents/list.md new file mode 100644 index 000000000..ca6148e03 --- /dev/null +++ b/content/en/api/php/beta/agents/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                \ No newline at end of file diff --git a/content/en/api/php/beta/agents/retrieve.md b/content/en/api/php/beta/agents/retrieve.md new file mode 100644 index 000000000..df1193e82 --- /dev/null +++ b/content/en/api/php/beta/agents/retrieve.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                  \ No newline at end of file diff --git a/content/en/api/php/beta/agents/update.md b/content/en/api/php/beta/agents/update.md new file mode 100644 index 000000000..ce6c2c858 --- /dev/null +++ b/content/en/api/php/beta/agents/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                    \ No newline at end of file diff --git a/content/en/api/php/beta/agents/versions.md b/content/en/api/php/beta/agents/versions.md new file mode 100644 index 000000000..05ad331f8 --- /dev/null +++ b/content/en/api/php/beta/agents/versions.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                      \ No newline at end of file diff --git a/content/en/api/php/beta/agents/versions/list.md b/content/en/api/php/beta/agents/versions/list.md new file mode 100644 index 000000000..248d4bdd0 --- /dev/null +++ b/content/en/api/php/beta/agents/versions/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                        \ No newline at end of file diff --git a/content/en/api/php/beta/environments.md b/content/en/api/php/beta/environments.md new file mode 100644 index 000000000..77b0417a7 --- /dev/null +++ b/content/en/api/php/beta/environments.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                          \ No newline at end of file diff --git a/content/en/api/php/beta/environments/archive.md b/content/en/api/php/beta/environments/archive.md new file mode 100644 index 000000000..a892f824e --- /dev/null +++ b/content/en/api/php/beta/environments/archive.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                            \ No newline at end of file diff --git a/content/en/api/php/beta/environments/create.md b/content/en/api/php/beta/environments/create.md new file mode 100644 index 000000000..e0724a758 --- /dev/null +++ b/content/en/api/php/beta/environments/create.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                              \ No newline at end of file diff --git a/content/en/api/php/beta/environments/delete.md b/content/en/api/php/beta/environments/delete.md new file mode 100644 index 000000000..ab5415061 --- /dev/null +++ b/content/en/api/php/beta/environments/delete.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                \ No newline at end of file diff --git a/content/en/api/php/beta/environments/list.md b/content/en/api/php/beta/environments/list.md new file mode 100644 index 000000000..b76daa5ad --- /dev/null +++ b/content/en/api/php/beta/environments/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/php/beta/environments/retrieve.md b/content/en/api/php/beta/environments/retrieve.md new file mode 100644 index 000000000..9785f6df5 --- /dev/null +++ b/content/en/api/php/beta/environments/retrieve.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/php/beta/environments/update.md b/content/en/api/php/beta/environments/update.md new file mode 100644 index 000000000..05e84fc9c --- /dev/null +++ b/content/en/api/php/beta/environments/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/php/beta/files.md b/content/en/api/php/beta/files.md index 2ae6834ce..8c946f6f4 100644 --- a/content/en/api/php/beta/files.md +++ b/content/en/api/php/beta/files.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                        \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/php/beta/files/delete.md b/content/en/api/php/beta/files/delete.md index 34b1c0cb0..b9db8895e 100644 --- a/content/en/api/php/beta/files/delete.md +++ b/content/en/api/php/beta/files/delete.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                            \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/php/beta/files/download.md b/content/en/api/php/beta/files/download.md index c13194408..ebb8b1343 100644 --- a/content/en/api/php/beta/files/download.md +++ b/content/en/api/php/beta/files/download.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/php/beta/files/list.md b/content/en/api/php/beta/files/list.md index c80b52d30..bef2a6745 100644 --- a/content/en/api/php/beta/files/list.md +++ b/content/en/api/php/beta/files/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                    \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/php/beta/files/retrieve_metadata.md b/content/en/api/php/beta/files/retrieve_metadata.md index 9b54ada1e..86c83a2be 100644 --- a/content/en/api/php/beta/files/retrieve_metadata.md +++ b/content/en/api/php/beta/files/retrieve_metadata.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                        \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/php/beta/files/upload.md b/content/en/api/php/beta/files/upload.md index 2d457caa3..3f7395ddb 100644 --- a/content/en/api/php/beta/files/upload.md +++ b/content/en/api/php/beta/files/upload.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                            \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/php/beta/messages.md b/content/en/api/php/beta/messages.md index 56603ebb9..33f5fd7ab 100644 --- a/content/en/api/php/beta/messages.md +++ b/content/en/api/php/beta/messages.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/php/beta/messages/batches.md b/content/en/api/php/beta/messages/batches.md index 1bf2266b1..3a8268e3f 100644 --- a/content/en/api/php/beta/messages/batches.md +++ b/content/en/api/php/beta/messages/batches.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                    \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/php/beta/messages/batches/cancel.md b/content/en/api/php/beta/messages/batches/cancel.md index c5cf4e971..d5700b97e 100644 --- a/content/en/api/php/beta/messages/batches/cancel.md +++ b/content/en/api/php/beta/messages/batches/cancel.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                        \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/php/beta/messages/batches/create.md b/content/en/api/php/beta/messages/batches/create.md index f8d00abfa..e61f0fe7b 100644 --- a/content/en/api/php/beta/messages/batches/create.md +++ b/content/en/api/php/beta/messages/batches/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                            \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/php/beta/messages/batches/delete.md b/content/en/api/php/beta/messages/batches/delete.md index bee3be146..7a95406ff 100644 --- a/content/en/api/php/beta/messages/batches/delete.md +++ b/content/en/api/php/beta/messages/batches/delete.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/php/beta/messages/batches/list.md b/content/en/api/php/beta/messages/batches/list.md index b8be02177..1288b5d23 100644 --- a/content/en/api/php/beta/messages/batches/list.md +++ b/content/en/api/php/beta/messages/batches/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                    \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/php/beta/messages/batches/results.md b/content/en/api/php/beta/messages/batches/results.md index 4548aa51b..7d833c8cc 100644 --- a/content/en/api/php/beta/messages/batches/results.md +++ b/content/en/api/php/beta/messages/batches/results.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                        \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/php/beta/messages/batches/retrieve.md b/content/en/api/php/beta/messages/batches/retrieve.md index b83863753..0f12de7ef 100644 --- a/content/en/api/php/beta/messages/batches/retrieve.md +++ b/content/en/api/php/beta/messages/batches/retrieve.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                            \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/php/beta/messages/count_tokens.md b/content/en/api/php/beta/messages/count_tokens.md index 014585ad7..0adec2c23 100644 --- a/content/en/api/php/beta/messages/count_tokens.md +++ b/content/en/api/php/beta/messages/count_tokens.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/php/beta/messages/create.md b/content/en/api/php/beta/messages/create.md index 05b238043..b72faa769 100644 --- a/content/en/api/php/beta/messages/create.md +++ b/content/en/api/php/beta/messages/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                    \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/php/beta/models.md b/content/en/api/php/beta/models.md index 143f5b078..3f04a7577 100644 --- a/content/en/api/php/beta/models.md +++ b/content/en/api/php/beta/models.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                        \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/php/beta/models/list.md b/content/en/api/php/beta/models/list.md index b47bb613c..94f71f94f 100644 --- a/content/en/api/php/beta/models/list.md +++ b/content/en/api/php/beta/models/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                            \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/php/beta/models/retrieve.md b/content/en/api/php/beta/models/retrieve.md index e376e4ad0..13373337e 100644 --- a/content/en/api/php/beta/models/retrieve.md +++ b/content/en/api/php/beta/models/retrieve.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/php/beta/sessions.md b/content/en/api/php/beta/sessions.md new file mode 100644 index 000000000..9aecce683 --- /dev/null +++ b/content/en/api/php/beta/sessions.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/archive.md b/content/en/api/php/beta/sessions/archive.md new file mode 100644 index 000000000..6fd78d382 --- /dev/null +++ b/content/en/api/php/beta/sessions/archive.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/create.md b/content/en/api/php/beta/sessions/create.md new file mode 100644 index 000000000..19622ab85 --- /dev/null +++ b/content/en/api/php/beta/sessions/create.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/delete.md b/content/en/api/php/beta/sessions/delete.md new file mode 100644 index 000000000..7e70f1f49 --- /dev/null +++ b/content/en/api/php/beta/sessions/delete.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/events.md b/content/en/api/php/beta/sessions/events.md new file mode 100644 index 000000000..2734a9d69 --- /dev/null +++ b/content/en/api/php/beta/sessions/events.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/events/list.md b/content/en/api/php/beta/sessions/events/list.md new file mode 100644 index 000000000..fa1d11369 --- /dev/null +++ b/content/en/api/php/beta/sessions/events/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/events/send.md b/content/en/api/php/beta/sessions/events/send.md new file mode 100644 index 000000000..2b32243f1 --- /dev/null +++ b/content/en/api/php/beta/sessions/events/send.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/events/stream.md b/content/en/api/php/beta/sessions/events/stream.md new file mode 100644 index 000000000..2174d4b5e --- /dev/null +++ b/content/en/api/php/beta/sessions/events/stream.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/list.md b/content/en/api/php/beta/sessions/list.md new file mode 100644 index 000000000..d3ec59561 --- /dev/null +++ b/content/en/api/php/beta/sessions/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/resources.md b/content/en/api/php/beta/sessions/resources.md new file mode 100644 index 000000000..54d07af89 --- /dev/null +++ b/content/en/api/php/beta/sessions/resources.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/resources/add.md b/content/en/api/php/beta/sessions/resources/add.md new file mode 100644 index 000000000..86905f16d --- /dev/null +++ b/content/en/api/php/beta/sessions/resources/add.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/resources/delete.md b/content/en/api/php/beta/sessions/resources/delete.md new file mode 100644 index 000000000..2b35e388f --- /dev/null +++ b/content/en/api/php/beta/sessions/resources/delete.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/resources/list.md b/content/en/api/php/beta/sessions/resources/list.md new file mode 100644 index 000000000..6512afa41 --- /dev/null +++ b/content/en/api/php/beta/sessions/resources/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/resources/retrieve.md b/content/en/api/php/beta/sessions/resources/retrieve.md new file mode 100644 index 000000000..2e38315f6 --- /dev/null +++ b/content/en/api/php/beta/sessions/resources/retrieve.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/resources/update.md b/content/en/api/php/beta/sessions/resources/update.md new file mode 100644 index 000000000..2c895b257 --- /dev/null +++ b/content/en/api/php/beta/sessions/resources/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/retrieve.md b/content/en/api/php/beta/sessions/retrieve.md new file mode 100644 index 000000000..2c9879c53 --- /dev/null +++ b/content/en/api/php/beta/sessions/retrieve.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/php/beta/sessions/update.md b/content/en/api/php/beta/sessions/update.md new file mode 100644 index 000000000..87dc39cfe --- /dev/null +++ b/content/en/api/php/beta/sessions/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/php/beta/skills.md b/content/en/api/php/beta/skills.md index b0f9e9ffb..1927fa45a 100644 --- a/content/en/api/php/beta/skills.md +++ b/content/en/api/php/beta/skills.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/php/beta/skills/create.md b/content/en/api/php/beta/skills/create.md index 67dbff7c4..4390deefb 100644 --- a/content/en/api/php/beta/skills/create.md +++ b/content/en/api/php/beta/skills/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/php/beta/skills/delete.md b/content/en/api/php/beta/skills/delete.md index 8ae059d8e..837a80ace 100644 --- a/content/en/api/php/beta/skills/delete.md +++ b/content/en/api/php/beta/skills/delete.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                              \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/php/beta/skills/list.md b/content/en/api/php/beta/skills/list.md index d957d3235..6beb02b82 100644 --- a/content/en/api/php/beta/skills/list.md +++ b/content/en/api/php/beta/skills/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                  \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/php/beta/skills/retrieve.md b/content/en/api/php/beta/skills/retrieve.md index 425270b9f..7810759dd 100644 --- a/content/en/api/php/beta/skills/retrieve.md +++ b/content/en/api/php/beta/skills/retrieve.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/php/beta/skills/versions.md b/content/en/api/php/beta/skills/versions.md index 6b630222d..cae01edc6 100644 --- a/content/en/api/php/beta/skills/versions.md +++ b/content/en/api/php/beta/skills/versions.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/php/beta/skills/versions/create.md b/content/en/api/php/beta/skills/versions/create.md index 00a376067..7869f8977 100644 --- a/content/en/api/php/beta/skills/versions/create.md +++ b/content/en/api/php/beta/skills/versions/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                              \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/php/beta/skills/versions/delete.md b/content/en/api/php/beta/skills/versions/delete.md index 6c7790c29..82075d962 100644 --- a/content/en/api/php/beta/skills/versions/delete.md +++ b/content/en/api/php/beta/skills/versions/delete.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                  \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/php/beta/skills/versions/list.md b/content/en/api/php/beta/skills/versions/list.md index f6cc11f82..b986a3e98 100644 --- a/content/en/api/php/beta/skills/versions/list.md +++ b/content/en/api/php/beta/skills/versions/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/php/beta/skills/versions/retrieve.md b/content/en/api/php/beta/skills/versions/retrieve.md index a3b467db8..4becad08c 100644 --- a/content/en/api/php/beta/skills/versions/retrieve.md +++ b/content/en/api/php/beta/skills/versions/retrieve.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/php/beta/vaults.md b/content/en/api/php/beta/vaults.md new file mode 100644 index 000000000..d97a3c178 --- /dev/null +++ b/content/en/api/php/beta/vaults.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/archive.md b/content/en/api/php/beta/vaults/archive.md new file mode 100644 index 000000000..c9c871d50 --- /dev/null +++ b/content/en/api/php/beta/vaults/archive.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/create.md b/content/en/api/php/beta/vaults/create.md new file mode 100644 index 000000000..a775f7e1d --- /dev/null +++ b/content/en/api/php/beta/vaults/create.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/credentials.md b/content/en/api/php/beta/vaults/credentials.md new file mode 100644 index 000000000..e564e4e61 --- /dev/null +++ b/content/en/api/php/beta/vaults/credentials.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/credentials/archive.md b/content/en/api/php/beta/vaults/credentials/archive.md new file mode 100644 index 000000000..cc4e24aa7 --- /dev/null +++ b/content/en/api/php/beta/vaults/credentials/archive.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/credentials/create.md b/content/en/api/php/beta/vaults/credentials/create.md new file mode 100644 index 000000000..8705bb738 --- /dev/null +++ b/content/en/api/php/beta/vaults/credentials/create.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/credentials/delete.md b/content/en/api/php/beta/vaults/credentials/delete.md new file mode 100644 index 000000000..a471b6620 --- /dev/null +++ b/content/en/api/php/beta/vaults/credentials/delete.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/credentials/list.md b/content/en/api/php/beta/vaults/credentials/list.md new file mode 100644 index 000000000..95dd37a31 --- /dev/null +++ b/content/en/api/php/beta/vaults/credentials/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/credentials/retrieve.md b/content/en/api/php/beta/vaults/credentials/retrieve.md new file mode 100644 index 000000000..59c2f9cfe --- /dev/null +++ b/content/en/api/php/beta/vaults/credentials/retrieve.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/credentials/update.md b/content/en/api/php/beta/vaults/credentials/update.md new file mode 100644 index 000000000..b6077937f --- /dev/null +++ b/content/en/api/php/beta/vaults/credentials/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/delete.md b/content/en/api/php/beta/vaults/delete.md new file mode 100644 index 000000000..69f7605cb --- /dev/null +++ b/content/en/api/php/beta/vaults/delete.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/list.md b/content/en/api/php/beta/vaults/list.md new file mode 100644 index 000000000..03e8a23da --- /dev/null +++ b/content/en/api/php/beta/vaults/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/retrieve.md b/content/en/api/php/beta/vaults/retrieve.md new file mode 100644 index 000000000..44f473d80 --- /dev/null +++ b/content/en/api/php/beta/vaults/retrieve.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/php/beta/vaults/update.md b/content/en/api/php/beta/vaults/update.md new file mode 100644 index 000000000..749a31708 --- /dev/null +++ b/content/en/api/php/beta/vaults/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/php/completions.md b/content/en/api/php/completions.md index 78e408a9a..c7f60980f 100644 --- a/content/en/api/php/completions.md +++ b/content/en/api/php/completions.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/php/completions/create.md b/content/en/api/php/completions/create.md index e951b16a7..42e7cf611 100644 --- a/content/en/api/php/completions/create.md +++ b/content/en/api/php/completions/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                              \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/php/messages.md b/content/en/api/php/messages.md index 2dcf24595..05acdaabb 100644 --- a/content/en/api/php/messages.md +++ b/content/en/api/php/messages.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/php/messages/batches.md b/content/en/api/php/messages/batches.md index d70f6114e..6fc5ce5b5 100644 --- a/content/en/api/php/messages/batches.md +++ b/content/en/api/php/messages/batches.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/php/messages/batches/cancel.md b/content/en/api/php/messages/batches/cancel.md index a175b77b6..d38ea1868 100644 --- a/content/en/api/php/messages/batches/cancel.md +++ b/content/en/api/php/messages/batches/cancel.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/php/messages/batches/create.md b/content/en/api/php/messages/batches/create.md index c75589a3c..c8ed1b1f7 100644 --- a/content/en/api/php/messages/batches/create.md +++ b/content/en/api/php/messages/batches/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/php/messages/batches/delete.md b/content/en/api/php/messages/batches/delete.md index 234950a9f..980d055ed 100644 --- a/content/en/api/php/messages/batches/delete.md +++ b/content/en/api/php/messages/batches/delete.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/php/messages/batches/list.md b/content/en/api/php/messages/batches/list.md index 4e854a263..e969de68e 100644 --- a/content/en/api/php/messages/batches/list.md +++ b/content/en/api/php/messages/batches/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/php/messages/batches/results.md b/content/en/api/php/messages/batches/results.md index 7b4a26ebe..e92048cca 100644 --- a/content/en/api/php/messages/batches/results.md +++ b/content/en/api/php/messages/batches/results.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/php/messages/batches/retrieve.md b/content/en/api/php/messages/batches/retrieve.md index 730e51723..0bc063d9b 100644 --- a/content/en/api/php/messages/batches/retrieve.md +++ b/content/en/api/php/messages/batches/retrieve.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/php/messages/count_tokens.md b/content/en/api/php/messages/count_tokens.md index d51f7692a..8df9c2771 100644 --- a/content/en/api/php/messages/count_tokens.md +++ b/content/en/api/php/messages/count_tokens.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/php/messages/create.md b/content/en/api/php/messages/create.md index 408ebb984..5dc50fa17 100644 --- a/content/en/api/php/messages/create.md +++ b/content/en/api/php/messages/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/php/models.md b/content/en/api/php/models.md index 83d0ce88f..09df89780 100644 --- a/content/en/api/php/models.md +++ b/content/en/api/php/models.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/php/models/list.md b/content/en/api/php/models/list.md index 1ede4c256..242bd53a7 100644 --- a/content/en/api/php/models/list.md +++ b/content/en/api/php/models/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/php/models/retrieve.md b/content/en/api/php/models/retrieve.md index abf087584..213073136 100644 --- a/content/en/api/php/models/retrieve.md +++ b/content/en/api/php/models/retrieve.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/python/beta.md b/content/en/api/python/beta.md index 940a78c19..d1b7a6719 100644 --- a/content/en/api/python/beta.md +++ b/content/en/api/python/beta.md @@ -4,11 +4,11 @@ ### Anthropic Beta -- `Union[str, Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]]` +- `Union[str, Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]]` - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -52,8 +52,6 @@ - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Beta API Error - `class BetaAPIError: …` @@ -338,7 +336,7 @@ The Models API response can be used to determine which models are available for - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -382,8 +380,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaModelInfo: …` @@ -604,7 +600,7 @@ The Models API response can be used to determine information about a specific mo - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -648,8 +644,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaModelInfo: …` @@ -3928,13 +3922,14 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -3950,9 +3945,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -6023,17 +6022,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. -- `user_profile_id: Optional[str]` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Optional[List[AnthropicBetaParam]]` Optional header to specify the beta version(s) you want to use. - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -6077,8 +6072,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessage: …` @@ -7002,13 +6995,14 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -7024,9 +7018,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -9934,13 +9932,14 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -9956,9 +9955,13 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -11937,7 +11940,7 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -11981,8 +11984,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageTokensCount: …` @@ -12013,7 +12014,7 @@ beta_message_tokens_count = client.beta.messages.count_tokens( "content": "string", "role": "user", }], - model="claude-opus-4-6", + model="claude-mythos-preview", ) print(beta_message_tokens_count.context_management) ``` @@ -19203,13 +19204,14 @@ print(beta_message_tokens_count.context_management) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -19225,9 +19227,13 @@ print(beta_message_tokens_count.context_management) - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -24563,13 +24569,14 @@ print(beta_message_tokens_count.context_management) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -24585,9 +24592,13 @@ print(beta_message_tokens_count.context_management) - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -25823,13 +25834,14 @@ print(beta_message_tokens_count.context_management) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -25845,9 +25857,13 @@ print(beta_message_tokens_count.context_management) - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -36979,13 +36995,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -37001,9 +37018,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -39072,17 +39093,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id: Optional[str]` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Optional[List[AnthropicBetaParam]]` Optional header to specify the beta version(s) you want to use. - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -39126,8 +39143,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` @@ -39265,7 +39280,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -39309,8 +39324,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` @@ -39448,7 +39461,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -39492,8 +39505,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` @@ -39622,7 +39633,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -39666,8 +39677,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` @@ -39797,7 +39806,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -39841,8 +39850,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaDeletedMessageBatch: …` @@ -39898,7 +39905,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -39942,8 +39949,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatchIndividualResponse: …` @@ -40885,13 +40890,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -40907,9 +40913,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -42480,13 +42490,14 @@ for batch in client.beta.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -42502,9 +42513,13 @@ for batch in client.beta.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -43868,13 +43883,14 @@ for batch in client.beta.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -43890,9 +43906,13 @@ for batch in client.beta.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -45218,13 +45238,14 @@ for batch in client.beta.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -45240,9 +45261,13 @@ for batch in client.beta.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -45543,21 +45568,401 @@ for batch in client.beta.messages.batches.results( - `"succeeded"` -# Files +# Agents -## Upload +## Create -`beta.files.upload(FileUploadParams**kwargs) -> FileMetadata` +`beta.agents.create(AgentCreateParams**kwargs) -> BetaManagedAgentsAgent` -**post** `/v1/files` +**post** `/v1/agents` -Upload File +Create Agent ### Parameters -- `file: FileTypes` +- `model: Model` - The file to upload + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `Union[Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more], str]` + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `class BetaManagedAgentsModelConfigParams: …` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +- `name: str` + + Human-readable name for the agent. 1-256 characters. + +- `description: Optional[str]` + + Description of what the agent does. Up to 2048 characters. + +- `mcp_servers: Optional[Iterable[BetaManagedAgentsURLMCPServerParams]]` + + MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `name: str` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + Endpoint URL for the MCP server. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + +- `skills: Optional[Iterable[BetaManagedAgentsSkillParams]]` + + Skills available to the agent. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams: …` + + An Anthropic-managed skill. + + - `skill_id: str` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams: …` + + A user-created custom skill. + + - `skill_id: str` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + +- `system: Optional[str]` + + System prompt for the agent. Up to 100,000 characters. + +- `tools: Optional[Iterable[Tool]]` + + Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params: …` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `configs: Optional[List[BetaManagedAgentsAgentToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: Optional[bool]` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsAgentToolsetDefaultConfigParams]` + + Default configuration for all tools in a toolset. + + - `enabled: Optional[bool]` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `class BetaManagedAgentsMCPToolsetParams: …` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: str` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `configs: Optional[List[BetaManagedAgentsMCPToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: str` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: Optional[bool]` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsMCPToolsetDefaultConfigParams]` + + Default configuration for all tools from an MCP server. + + - `enabled: Optional[bool]` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `class BetaManagedAgentsCustomToolParams: …` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: str` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: Literal["custom"]` + + - `"custom"` - `betas: Optional[List[AnthropicBetaParam]]` @@ -45565,7 +45970,7 @@ Upload File - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -45609,7 +46014,22752 @@ Upload File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_agent = client.beta.agents.create( + model="claude-sonnet-4-6", + name="My First Agent", +) +print(beta_managed_agents_agent.id) +``` + +## List + +`beta.agents.list(AgentListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsAgent]` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `created_at_gte: Optional[Union[str, datetime]]` + + Return agents created at or after this time (inclusive). + +- `created_at_lte: Optional[Union[str, datetime]]` + + Return agents created at or before this time (inclusive). + +- `include_archived: Optional[bool]` + + Include archived agents in results. Defaults to false. + +- `limit: Optional[int]` + + Maximum results per page. Default 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination cursor from a previous response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.agents.list() +page = page.data[0] +print(page.id) +``` + +## Retrieve + +`beta.agents.retrieve(stragent_id, AgentRetrieveParams**kwargs) -> BetaManagedAgentsAgent` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `agent_id: str` + +- `version: Optional[int]` + + Agent version. Omit for the most recent version. Must be at least 1 if specified. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_agent = client.beta.agents.retrieve( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", +) +print(beta_managed_agents_agent.id) +``` + +## Update + +`beta.agents.update(stragent_id, AgentUpdateParams**kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `agent_id: str` + +- `version: int` + + The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + +- `description: Optional[str]` + + Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + +- `mcp_servers: Optional[Iterable[BetaManagedAgentsURLMCPServerParams]]` + + MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `name: str` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + Endpoint URL for the MCP server. + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + +- `model: Optional[Model]` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `Union[Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more], str]` + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `class BetaManagedAgentsModelConfigParams: …` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +- `name: Optional[str]` + + Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + +- `skills: Optional[Iterable[BetaManagedAgentsSkillParams]]` + + Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams: …` + + An Anthropic-managed skill. + + - `skill_id: str` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams: …` + + A user-created custom skill. + + - `skill_id: str` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + +- `system: Optional[str]` + + System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + +- `tools: Optional[Iterable[Tool]]` + + Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params: …` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `configs: Optional[List[BetaManagedAgentsAgentToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: Optional[bool]` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsAgentToolsetDefaultConfigParams]` + + Default configuration for all tools in a toolset. + + - `enabled: Optional[bool]` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `class BetaManagedAgentsMCPToolsetParams: …` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: str` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `configs: Optional[List[BetaManagedAgentsMCPToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: str` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: Optional[bool]` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsMCPToolsetDefaultConfigParams]` + + Default configuration for all tools from an MCP server. + + - `enabled: Optional[bool]` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `class BetaManagedAgentsCustomToolParams: …` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: str` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: Literal["custom"]` + + - `"custom"` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_agent = client.beta.agents.update( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", + version=1, +) +print(beta_managed_agents_agent.id) +``` + +## Archive + +`beta.agents.archive(stragent_id, AgentArchiveParams**kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `agent_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_agent = client.beta.agents.archive( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", +) +print(beta_managed_agents_agent.id) +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `class BetaManagedAgentsAgentToolConfig: …` + + Configuration for a specific agent tool. + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Agent Tool Config Params + +- `class BetaManagedAgentsAgentToolConfigParams: …` + + Configuration override for a specific tool within a toolset. + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: Optional[bool]` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config + +- `class BetaManagedAgentsAgentToolsetDefaultConfig: …` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `class BetaManagedAgentsAgentToolsetDefaultConfigParams: …` + + Default configuration for all tools in a toolset. + + - `enabled: Optional[bool]` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset20260401 + +- `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `class BetaManagedAgentsAgentToolset20260401Params: …` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `configs: Optional[List[BetaManagedAgentsAgentToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: Optional[bool]` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsAgentToolsetDefaultConfigParams]` + + Default configuration for all tools in a toolset. + + - `enabled: Optional[bool]` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Always Allow Policy + +- `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + +### Beta Managed Agents Always Ask Policy + +- `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Anthropic Skill + +- `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + +### Beta Managed Agents Anthropic Skill Params + +- `class BetaManagedAgentsAnthropicSkillParams: …` + + An Anthropic-managed skill. + + - `skill_id: str` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + +### Beta Managed Agents Custom Skill Params + +- `class BetaManagedAgentsCustomSkillParams: …` + + A user-created custom skill. + + - `skill_id: str` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + +### Beta Managed Agents Custom Tool Input Schema + +- `class BetaManagedAgentsCustomToolInputSchema: …` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + +### Beta Managed Agents Custom Tool Params + +- `class BetaManagedAgentsCustomToolParams: …` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: str` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: Literal["custom"]` + + - `"custom"` + +### Beta Managed Agents MCP Server URL Definition + +- `class BetaManagedAgentsMCPServerURLDefinition: …` + + URL-based MCP server connection as returned in API responses. + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + +### Beta Managed Agents MCP Tool Config + +- `class BetaManagedAgentsMCPToolConfig: …` + + Resolved configuration for a specific MCP tool. + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents MCP Tool Config Params + +- `class BetaManagedAgentsMCPToolConfigParams: …` + + Configuration override for a specific MCP tool. + + - `name: str` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: Optional[bool]` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset + +- `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + +### Beta Managed Agents MCP Toolset Default Config + +- `class BetaManagedAgentsMCPToolsetDefaultConfig: …` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `class BetaManagedAgentsMCPToolsetDefaultConfigParams: …` + + Default configuration for all tools from an MCP server. + + - `enabled: Optional[bool]` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Params + +- `class BetaManagedAgentsMCPToolsetParams: …` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: str` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `configs: Optional[List[BetaManagedAgentsMCPToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: str` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: Optional[bool]` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsMCPToolsetDefaultConfigParams]` + + Default configuration for all tools from an MCP server. + + - `enabled: Optional[bool]` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Model + +- `Union[Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more], str]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + +### Beta Managed Agents Model Config + +- `class BetaManagedAgentsModelConfig: …` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Model Config Params + +- `class BetaManagedAgentsModelConfigParams: …` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Skill Params + +- `BetaManagedAgentsSkillParams` + + Skill to load in the session container. + + - `class BetaManagedAgentsAnthropicSkillParams: …` + + An Anthropic-managed skill. + + - `skill_id: str` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams: …` + + A user-created custom skill. + + - `skill_id: str` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `class BetaManagedAgentsURLMCPServerParams: …` + + URL-based MCP server connection. + + - `name: str` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + Endpoint URL for the MCP server. + +# Versions + +## List + +`beta.agents.versions.list(stragent_id, VersionListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsAgent]` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agent_id: str` + +- `limit: Optional[int]` + + Maximum results per page. Default 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination cursor. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.agents.versions.list( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", +) +page = page.data[0] +print(page.id) +``` + +# Environments + +## Create + +`beta.environments.create(EnvironmentCreateParams**kwargs) -> BetaEnvironment` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `name: str` + + Human-readable name for the environment + +- `config: Optional[BetaCloudConfigParams]` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `networking: Optional[Networking]` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetworkParams: …` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: Optional[bool]` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: Optional[bool]` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Optional[List[str]]` + + Specifies domains the container can reach. + + - `packages: Optional[BetaPackagesParams]` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Optional[List[str]]` + + Ubuntu/Debian packages to install + + - `cargo: Optional[List[str]]` + + Rust packages to install + + - `gem: Optional[List[str]]` + + Ruby packages to install + + - `go: Optional[List[str]]` + + Go packages to install + + - `npm: Optional[List[str]]` + + Node.js packages to install + + - `pip: Optional[List[str]]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + +- `description: Optional[str]` + + Optional description of the environment + +- `metadata: Optional[Dict[str, str]]` + + User-provided metadata key-value pairs + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment = client.beta.environments.create( + name="python-data-analysis", +) +print(beta_environment.id) +``` + +## List + +`beta.environments.list(EnvironmentListParams**kwargs) -> SyncPageCursor[BetaEnvironment]` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `include_archived: Optional[bool]` + + Include archived environments in the response + +- `limit: Optional[int]` + + Maximum number of environments to return + +- `page: Optional[str]` + + Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.environments.list() +page = page.data[0] +print(page.id) +``` + +## Retrieve + +`beta.environments.retrieve(strenvironment_id, EnvironmentRetrieveParams**kwargs) -> BetaEnvironment` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `environment_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment = client.beta.environments.retrieve( + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_environment.id) +``` + +## Update + +`beta.environments.update(strenvironment_id, EnvironmentUpdateParams**kwargs) -> BetaEnvironment` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `environment_id: str` + +- `config: Optional[BetaCloudConfigParams]` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `networking: Optional[Networking]` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetworkParams: …` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: Optional[bool]` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: Optional[bool]` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Optional[List[str]]` + + Specifies domains the container can reach. + + - `packages: Optional[BetaPackagesParams]` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Optional[List[str]]` + + Ubuntu/Debian packages to install + + - `cargo: Optional[List[str]]` + + Rust packages to install + + - `gem: Optional[List[str]]` + + Ruby packages to install + + - `go: Optional[List[str]]` + + Go packages to install + + - `npm: Optional[List[str]]` + + Node.js packages to install + + - `pip: Optional[List[str]]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + +- `description: Optional[str]` + + Updated description of the environment + +- `metadata: Optional[Dict[str, Optional[str]]]` + + User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + +- `name: Optional[str]` + + Updated name for the environment + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment = client.beta.environments.update( + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_environment.id) +``` + +## Delete + +`beta.environments.delete(strenvironment_id, EnvironmentDeleteParams**kwargs) -> BetaEnvironmentDeleteResponse` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `environment_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironmentDeleteResponse: …` + + Response after deleting an environment. + + - `id: str` + + Environment identifier + + - `type: Literal["environment_deleted"]` + + The type of response + + - `"environment_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment_delete_response = client.beta.environments.delete( + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_environment_delete_response.id) +``` + +## Archive + +`beta.environments.archive(strenvironment_id, EnvironmentArchiveParams**kwargs) -> BetaEnvironment` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `environment_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment = client.beta.environments.archive( + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_environment.id) +``` + +## Domain Types + +### Beta Cloud Config + +- `class BetaCloudConfig: …` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + +### Beta Cloud Config Params + +- `class BetaCloudConfigParams: …` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `networking: Optional[Networking]` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetworkParams: …` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: Optional[bool]` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: Optional[bool]` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Optional[List[str]]` + + Specifies domains the container can reach. + + - `packages: Optional[BetaPackagesParams]` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Optional[List[str]]` + + Ubuntu/Debian packages to install + + - `cargo: Optional[List[str]]` + + Rust packages to install + + - `gem: Optional[List[str]]` + + Ruby packages to install + + - `go: Optional[List[str]]` + + Go packages to install + + - `npm: Optional[List[str]]` + + Node.js packages to install + + - `pip: Optional[List[str]]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + +### Beta Environment + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `class BetaEnvironmentDeleteResponse: …` + + Response after deleting an environment. + + - `id: str` + + Environment identifier + + - `type: Literal["environment_deleted"]` + + The type of response + + - `"environment_deleted"` + +### Beta Limited Network + +- `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + +### Beta Limited Network Params + +- `class BetaLimitedNetworkParams: …` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: Optional[bool]` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: Optional[bool]` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Optional[List[str]]` + + Specifies domains the container can reach. + +### Beta Packages + +- `class BetaPackages: …` + + Packages (and their versions) available in this environment. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + +### Beta Packages Params + +- `class BetaPackagesParams: …` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Optional[List[str]]` + + Ubuntu/Debian packages to install + + - `cargo: Optional[List[str]]` + + Rust packages to install + + - `gem: Optional[List[str]]` + + Ruby packages to install + + - `go: Optional[List[str]]` + + Go packages to install + + - `npm: Optional[List[str]]` + + Node.js packages to install + + - `pip: Optional[List[str]]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + +### Beta Unrestricted Network + +- `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + +# Sessions + +## Create + +`beta.sessions.create(SessionCreateParams**kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `agent: Agent` + + Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `str` + + - `class BetaManagedAgentsAgentParams: …` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: str` + + The `agent` ID. + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: Optional[int]` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +- `environment_id: str` + + ID of the `environment` defining the container configuration for this session. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata attached to the session. + +- `resources: Optional[Iterable[Resource]]` + + Resources (e.g. repositories, files) to mount into the session's container. + + - `class BetaManagedAgentsGitHubRepositoryResourceParams: …` + + Mount a GitHub repository into the session's container. + + - `authorization_token: str` + + GitHub authorization token used to clone the repository. + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `url: str` + + Github URL of the repository + + - `checkout: Optional[Checkout]` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/workspace/`. + + - `class BetaManagedAgentsFileResourceParams: …` + + Mount a file uploaded via the Files API into the session. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `title: Optional[str]` + + Human-readable session title. + +- `vault_ids: Optional[Sequence[str]]` + + Vault IDs for stored credentials the agent can use during the session. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_session = client.beta.sessions.create( + agent="agent_011CZkYpogX7uDKUyvBTophP", + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_managed_agents_session.id) +``` + +## List + +`beta.sessions.list(SessionListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSession]` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `agent_id: Optional[str]` + + Filter sessions created with this agent ID. + +- `agent_version: Optional[int]` + + Filter by agent version. Only applies when agent_id is also set. + +- `created_at_gt: Optional[Union[str, datetime]]` + + Return sessions created after this time (exclusive). + +- `created_at_gte: Optional[Union[str, datetime]]` + + Return sessions created at or after this time (inclusive). + +- `created_at_lt: Optional[Union[str, datetime]]` + + Return sessions created before this time (exclusive). + +- `created_at_lte: Optional[Union[str, datetime]]` + + Return sessions created at or before this time (inclusive). + +- `include_archived: Optional[bool]` + + When true, includes archived sessions. Default: false (exclude archived). + +- `limit: Optional[int]` + + Maximum number of results to return. + +- `order: Optional[Literal["asc", "desc"]]` + + Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `"asc"` + + - `"desc"` + +- `page: Optional[str]` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.sessions.list() +page = page.data[0] +print(page.id) +``` + +## Retrieve + +`beta.sessions.retrieve(strsession_id, SessionRetrieveParams**kwargs) -> BetaManagedAgentsSession` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_session = client.beta.sessions.retrieve( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_session.id) +``` + +## Update + +`beta.sessions.update(strsession_id, SessionUpdateParams**kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `session_id: str` + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + +- `title: Optional[str]` + + Human-readable session title. + +- `vault_ids: Optional[Sequence[str]]` + + Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_session = client.beta.sessions.update( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_session.id) +``` + +## Delete + +`beta.sessions.delete(strsession_id, SessionDeleteParams**kwargs) -> BetaManagedAgentsDeletedSession` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedSession: …` + + Confirmation that a `session` has been permanently deleted. + + - `id: str` + + - `type: Literal["session_deleted"]` + + - `"session_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_deleted_session = client.beta.sessions.delete( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_deleted_session.id) +``` + +## Archive + +`beta.sessions.archive(strsession_id, SessionArchiveParams**kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_session = client.beta.sessions.archive( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_session.id) +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `class BetaManagedAgentsAgentParams: …` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: str` + + The `agent` ID. + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: Optional[int]` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + +### Beta Managed Agents Cache Creation Usage + +- `class BetaManagedAgentsCacheCreationUsage: …` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + +### Beta Managed Agents Deleted Session + +- `class BetaManagedAgentsDeletedSession: …` + + Confirmation that a `session` has been permanently deleted. + + - `id: str` + + - `type: Literal["session_deleted"]` + + - `"session_deleted"` + +### Beta Managed Agents File Resource Params + +- `class BetaManagedAgentsFileResourceParams: …` + + Mount a file uploaded via the Files API into the session. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `class BetaManagedAgentsGitHubRepositoryResourceParams: …` + + Mount a GitHub repository into the session's container. + + - `authorization_token: str` + + GitHub authorization token used to clone the repository. + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `url: str` + + Github URL of the repository + + - `checkout: Optional[Checkout]` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `class BetaManagedAgentsSessionAgent: …` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + +### Beta Managed Agents Session Stats + +- `class BetaManagedAgentsSessionStats: …` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `class BetaManagedAgentsSessionUsage: …` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + +# Events + +## List + +`beta.sessions.events.list(strsession_id, EventListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSessionEvent]` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `session_id: str` + +- `limit: Optional[int]` + + Query parameter for limit + +- `order: Optional[Literal["asc", "desc"]]` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"` + + - `"desc"` + +- `page: Optional[str]` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionEvent` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.sessions.events.list( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +page = page.data[0] +print(page) +``` + +## Send + +`beta.sessions.events.send(strsession_id, EventSendParams**kwargs) -> BetaManagedAgentsSendSessionEvents` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `session_id: str` + +- `events: Iterable[BetaManagedAgentsEventParams]` + + Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams: …` + + Parameters for sending a user message to the session. + + - `content: List[Content]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams: …` + + Parameters for sending an interrupt to pause the agent. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams: …` + + Parameters for confirming or denying a tool execution request. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams: …` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSendSessionEvents: …` + + Events that were successfully sent to the session. + + - `data: Optional[List[Data]]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_send_session_events = client.beta.sessions.events.send( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", + events=[{ + "content": [{ + "text": "Where is my order #1234?", + "type": "text", + }], + "type": "user.message", + }], +) +print(beta_managed_agents_send_session_events.data) +``` + +## Stream + +`beta.sessions.events.stream(strsession_id, EventStreamParams**kwargs) -> BetaManagedAgentsStreamSessionEvents` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +for event in client.beta.sessions.events.stream( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +): + print(event) +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Agent Message Event + +- `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Base64 Document Source + +- `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + +### Beta Managed Agents Base64 Image Source + +- `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + +### Beta Managed Agents Billing Error + +- `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + +### Beta Managed Agents Document Block + +- `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + +### Beta Managed Agents Event Params + +- `BetaManagedAgentsEventParams` + + Union type for event parameters that can be sent to a session. + + - `class BetaManagedAgentsUserMessageEventParams: …` + + Parameters for sending a user message to the session. + + - `content: List[Content]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams: …` + + Parameters for sending an interrupt to pause the agent. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams: …` + + Parameters for confirming or denying a tool execution request. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams: …` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + +### Beta Managed Agents File Image Source + +- `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + +### Beta Managed Agents Image Block + +- `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + +### Beta Managed Agents Retry Status Exhausted + +- `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + +### Beta Managed Agents Send Session Events + +- `class BetaManagedAgentsSendSessionEvents: …` + + Events that were successfully sent to the session. + + - `data: Optional[List[Data]]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + +### Beta Managed Agents Session Error Event + +- `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + +### Beta Managed Agents Session Event + +- `BetaManagedAgentsSessionEvent` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `class BetaManagedAgentsSpanModelUsage: …` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Stream Session Events + +- `BetaManagedAgentsStreamSessionEvents` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Beta Managed Agents Text Block + +- `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + +### Beta Managed Agents Unknown Error + +- `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + +### Beta Managed Agents URL Document Source + +- `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `class BetaManagedAgentsUserCustomToolResultEventParams: …` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `class BetaManagedAgentsUserInterruptEventParams: …` + + Parameters for sending an interrupt to pause the agent. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `class BetaManagedAgentsUserMessageEventParams: …` + + Parameters for sending a user message to the session. + + - `content: List[Content]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `class BetaManagedAgentsUserToolConfirmationEventParams: …` + + Parameters for confirming or denying a tool execution request. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`beta.sessions.resources.add(strsession_id, ResourceAddParams**kwargs) -> BetaManagedAgentsFileResource` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `session_id: str` + +- `file_id: str` + + ID of a previously uploaded file. + +- `type: Literal["file"]` + + - `"file"` + +- `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_file_resource = client.beta.sessions.resources.add( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", + file_id="file_011CNha8iCJcU1wXNR6q4V8w", + type="file", +) +print(beta_managed_agents_file_resource.id) +``` + +## List + +`beta.sessions.resources.list(strsession_id, ResourceListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSessionResource]` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `session_id: str` + +- `limit: Optional[int]` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `page: Optional[str]` + + Opaque cursor from a previous response's next_page field. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionResource` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.sessions.resources.list( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +page = page.data[0] +print(page) +``` + +## Retrieve + +`beta.sessions.resources.retrieve(strresource_id, ResourceRetrieveParams**kwargs) -> ResourceRetrieveResponse` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `session_id: str` + +- `resource_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceRetrieveResponse` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +resource = client.beta.sessions.resources.retrieve( + resource_id="sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(resource) +``` + +## Update + +`beta.sessions.resources.update(strresource_id, ResourceUpdateParams**kwargs) -> ResourceUpdateResponse` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `session_id: str` + +- `resource_id: str` + +- `authorization_token: str` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceUpdateResponse` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +resource = client.beta.sessions.resources.update( + resource_id="sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", + authorization_token="ghp_exampletoken", +) +print(resource) +``` + +## Delete + +`beta.sessions.resources.delete(strresource_id, ResourceDeleteParams**kwargs) -> BetaManagedAgentsDeleteSessionResource` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `session_id: str` + +- `resource_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource: …` + + Confirmation of resource deletion. + + - `id: str` + + - `type: Literal["session_resource_deleted"]` + + - `"session_resource_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_delete_session_resource = client.beta.sessions.resources.delete( + resource_id="sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_delete_session_resource.id) +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `class BetaManagedAgentsDeleteSessionResource: …` + + Confirmation of resource deletion. + + - `id: str` + + - `type: Literal["session_resource_deleted"]` + + - `"session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + +### Beta Managed Agents Session Resource + +- `BetaManagedAgentsSessionResource` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Resource Retrieve Response + +- `ResourceRetrieveResponse` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Resource Update Response + +- `ResourceUpdateResponse` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +# Vaults + +## Create + +`beta.vaults.create(VaultCreateParams**kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `display_name: str` + + Human-readable name for the vault. 1-255 characters. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata to attach to the vault. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_vault = client.beta.vaults.create( + display_name="Example vault", +) +print(beta_managed_agents_vault.id) +``` + +## List + +`beta.vaults.list(VaultListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsVault]` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `include_archived: Optional[bool]` + + Whether to include archived vaults in the results. + +- `limit: Optional[int]` + + Maximum number of vaults to return per page. Defaults to 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination token from a previous `list_vaults` response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.vaults.list() +page = page.data[0] +print(page.id) +``` + +## Retrieve + +`beta.vaults.retrieve(strvault_id, VaultRetrieveParams**kwargs) -> BetaManagedAgentsVault` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `vault_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_vault = client.beta.vaults.retrieve( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_vault.id) +``` + +## Update + +`beta.vaults.update(strvault_id, VaultUpdateParams**kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `vault_id: str` + +- `display_name: Optional[str]` + + Updated human-readable name for the vault. 1-255 characters. + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_vault = client.beta.vaults.update( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_vault.id) +``` + +## Delete + +`beta.vaults.delete(strvault_id, VaultDeleteParams**kwargs) -> BetaManagedAgentsDeletedVault` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `vault_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedVault: …` + + Confirmation of a deleted vault. + + - `id: str` + + Unique identifier of the deleted vault. + + - `type: Literal["vault_deleted"]` + + - `"vault_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_deleted_vault = client.beta.vaults.delete( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_deleted_vault.id) +``` + +## Archive + +`beta.vaults.archive(strvault_id, VaultArchiveParams**kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `vault_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_vault = client.beta.vaults.archive( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_vault.id) +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `class BetaManagedAgentsDeletedVault: …` + + Confirmation of a deleted vault. + + - `id: str` + + Unique identifier of the deleted vault. + + - `type: Literal["vault_deleted"]` + + - `"vault_deleted"` + +### Beta Managed Agents Vault + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`beta.vaults.credentials.create(strvault_id, CredentialCreateParams**kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vault_id: str` + +- `auth: Auth` + + Authentication details for creating a credential. + + - `class BetaManagedAgentsMCPOAuthCreateParams: …` + + Parameters for creating an MCP OAuth credential. + + - `access_token: str` + + OAuth access token. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshParams]` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: str` + + OAuth client ID. + + - `refresh_token: str` + + OAuth refresh token. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams: …` + + Parameters for creating a static bearer token credential. + + - `token: str` + + Static bearer token value. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + +- `display_name: Optional[str]` + + Human-readable name for the credential. Up to 255 characters. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata to attach to the credential. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.create( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", + auth={ + "token": "bearer_exampletoken", + "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", + "type": "static_bearer", + }, +) +print(beta_managed_agents_credential.id) +``` + +## List + +`beta.vaults.credentials.list(strvault_id, CredentialListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsCredential]` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vault_id: str` + +- `include_archived: Optional[bool]` + + Whether to include archived credentials in the results. + +- `limit: Optional[int]` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination token from a previous `list_credentials` response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.vaults.credentials.list( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +page = page.data[0] +print(page.id) +``` + +## Retrieve + +`beta.vaults.credentials.retrieve(strcredential_id, CredentialRetrieveParams**kwargs) -> BetaManagedAgentsCredential` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.retrieve( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_credential.id) +``` + +## Update + +`beta.vaults.credentials.update(strcredential_id, CredentialUpdateParams**kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `auth: Optional[Auth]` + + Updated authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthUpdateParams: …` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `access_token: Optional[str]` + + Updated OAuth access token. + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshUpdateParams]` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: Optional[str]` + + Updated OAuth refresh token. + + - `scope: Optional[str]` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: Optional[TokenEndpointAuth]` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams: …` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `token: Optional[str]` + + Updated static bearer token value. + +- `display_name: Optional[str]` + + Updated human-readable name for the credential. 1-255 characters. + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.update( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_credential.id) +``` + +## Delete + +`beta.vaults.credentials.delete(strcredential_id, CredentialDeleteParams**kwargs) -> BetaManagedAgentsDeletedCredential` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedCredential: …` + + Confirmation of a deleted credential. + + - `id: str` + + Unique identifier of the deleted credential. + + - `type: Literal["vault_credential_deleted"]` + + - `"vault_credential_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_deleted_credential = client.beta.vaults.credentials.delete( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_deleted_credential.id) +``` + +## Archive + +`beta.vaults.credentials.archive(strcredential_id, CredentialArchiveParams**kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.archive( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_credential.id) +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `class BetaManagedAgentsDeletedCredential: …` + + Confirmation of a deleted credential. + + - `id: str` + + Unique identifier of the deleted credential. + + - `type: Literal["vault_credential_deleted"]` + + - `"vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `class BetaManagedAgentsMCPOAuthCreateParams: …` + + Parameters for creating an MCP OAuth credential. + + - `access_token: str` + + OAuth access token. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshParams]` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: str` + + OAuth client ID. + + - `refresh_token: str` + + OAuth refresh token. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `class BetaManagedAgentsMCPOAuthRefreshParams: …` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: str` + + OAuth client ID. + + - `refresh_token: str` + + OAuth refresh token. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `class BetaManagedAgentsMCPOAuthRefreshResponse: …` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `class BetaManagedAgentsMCPOAuthRefreshUpdateParams: …` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: Optional[str]` + + Updated OAuth refresh token. + + - `scope: Optional[str]` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: Optional[TokenEndpointAuth]` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `class BetaManagedAgentsMCPOAuthUpdateParams: …` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `access_token: Optional[str]` + + Updated OAuth access token. + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshUpdateParams]` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: Optional[str]` + + Updated OAuth refresh token. + + - `scope: Optional[str]` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: Optional[TokenEndpointAuth]` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `class BetaManagedAgentsStaticBearerCreateParams: …` + + Parameters for creating a static bearer token credential. + + - `token: str` + + Static bearer token value. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `class BetaManagedAgentsStaticBearerUpdateParams: …` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `token: Optional[str]` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + +# Files + +## Upload + +`beta.files.upload(FileUploadParams**kwargs) -> FileMetadata` + +**post** `/v1/files` + +Upload File + +### Parameters + +- `file: FileTypes` + + The file to upload + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` ### Returns @@ -45649,6 +68799,20 @@ Upload File Whether the file can be downloaded. + - `scope: Optional[BetaFileScope]` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```python @@ -45688,13 +68852,17 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. +- `scope_id: Optional[str]` + + Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `betas: Optional[List[AnthropicBetaParam]]` Optional header to specify the beta version(s) you want to use. - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -45738,8 +68906,6 @@ List Files - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata: …` @@ -45778,6 +68944,20 @@ List Files Whether the file can be downloaded. + - `scope: Optional[BetaFileScope]` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```python @@ -45812,7 +68992,7 @@ Download File - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -45856,8 +69036,6 @@ Download File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BinaryResponseContent` @@ -45899,7 +69077,7 @@ Get File Metadata - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -45943,8 +69121,6 @@ Get File Metadata - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata: …` @@ -45983,6 +69159,20 @@ Get File Metadata Whether the file can be downloaded. + - `scope: Optional[BetaFileScope]` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```python @@ -46018,7 +69208,7 @@ Delete File - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -46062,8 +69252,6 @@ Delete File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class DeletedFile: …` @@ -46097,6 +69285,20 @@ print(deleted_file.id) ## Domain Types +### Beta File Scope + +- `class BetaFileScope: …` + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Deleted File - `class DeletedFile: …` @@ -46151,6 +69353,20 @@ print(deleted_file.id) Whether the file can be downloaded. + - `scope: Optional[BetaFileScope]` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` + # Skills ## Create @@ -46181,7 +69397,7 @@ Create Skill - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -46225,8 +69441,6 @@ Create Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class SkillCreateResponse: …` @@ -46322,7 +69536,7 @@ List Skills - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -46366,8 +69580,6 @@ List Skills - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class SkillListResponse: …` @@ -46449,7 +69661,7 @@ Get Skill - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -46493,8 +69705,6 @@ Get Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class SkillRetrieveResponse: …` @@ -46577,7 +69787,7 @@ Delete Skill - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -46621,8 +69831,6 @@ Delete Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class SkillDeleteResponse: …` @@ -46837,7 +70045,7 @@ Create Skill Version - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -46881,8 +70089,6 @@ Create Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionCreateResponse: …` @@ -46978,7 +70184,7 @@ List Skill Versions - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -47022,8 +70228,6 @@ List Skill Versions - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionListResponse: …` @@ -47116,7 +70320,7 @@ Get Skill Version - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -47160,8 +70364,6 @@ Get Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionRetrieveResponse: …` @@ -47254,7 +70456,7 @@ Delete Skill Version - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -47298,8 +70500,6 @@ Delete Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionDeleteResponse: …` @@ -47493,573 +70693,3 @@ print(version.id) Deleted object type. For Skill Versions, this is always `"skill_version_deleted"`. - -# User Profiles - -## Create - -`beta.user_profiles.create(UserProfileCreateParams**kwargs) -> BetaUserProfile` - -**post** `/v1/user_profiles` - -Create User Profile - -### Parameters - -- `external_id: Optional[str]` - -- `metadata: Optional[Dict[str, str]]` - - Free-form key-value data to attach to this user profile. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. Values must be non-empty strings. - -- `betas: Optional[List[AnthropicBetaParam]]` - - Optional header to specify the beta version(s) you want to use. - - - `str` - - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `class BetaUserProfile: …` - - - `id: str` - - - `created_at: datetime` - - A timestamp in RFC 3339 format - - - `metadata: Dict[str, str]` - - - `trust_grants: Dict[str, BetaUserProfileTrustGrant]` - - - `status: str` - - - `type: str` - - - `updated_at: datetime` - - A timestamp in RFC 3339 format - - - `external_id: Optional[str]` - -### Example - -```python -import os -from anthropic import Anthropic - -client = Anthropic( - api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted -) -beta_user_profile = client.beta.user_profiles.create() -print(beta_user_profile.id) -``` - -## List - -`beta.user_profiles.list(UserProfileListParams**kwargs) -> SyncPageCursorV2[BetaUserProfile]` - -**get** `/v1/user_profiles` - -List User Profiles - -### Parameters - -- `limit: Optional[int]` - - Query parameter for limit - -- `order: Optional[Literal["asc", "desc"]]` - - Query parameter for order - - - `"asc"` - - - `"desc"` - -- `page: Optional[str]` - - Query parameter for page - -- `betas: Optional[List[AnthropicBetaParam]]` - - Optional header to specify the beta version(s) you want to use. - - - `str` - - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `class BetaUserProfile: …` - - - `id: str` - - - `created_at: datetime` - - A timestamp in RFC 3339 format - - - `metadata: Dict[str, str]` - - - `trust_grants: Dict[str, BetaUserProfileTrustGrant]` - - - `status: str` - - - `type: str` - - - `updated_at: datetime` - - A timestamp in RFC 3339 format - - - `external_id: Optional[str]` - -### Example - -```python -import os -from anthropic import Anthropic - -client = Anthropic( - api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted -) -page = client.beta.user_profiles.list() -page = page.data[0] -print(page.id) -``` - -## Retrieve - -`beta.user_profiles.retrieve(strid, UserProfileRetrieveParams**kwargs) -> BetaUserProfile` - -**get** `/v1/user_profiles/{id}` - -Get User Profile - -### Parameters - -- `id: str` - -- `betas: Optional[List[AnthropicBetaParam]]` - - Optional header to specify the beta version(s) you want to use. - - - `str` - - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `class BetaUserProfile: …` - - - `id: str` - - - `created_at: datetime` - - A timestamp in RFC 3339 format - - - `metadata: Dict[str, str]` - - - `trust_grants: Dict[str, BetaUserProfileTrustGrant]` - - - `status: str` - - - `type: str` - - - `updated_at: datetime` - - A timestamp in RFC 3339 format - - - `external_id: Optional[str]` - -### Example - -```python -import os -from anthropic import Anthropic - -client = Anthropic( - api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted -) -beta_user_profile = client.beta.user_profiles.retrieve( - id="id", -) -print(beta_user_profile.id) -``` - -## Update - -`beta.user_profiles.update(strid, UserProfileUpdateParams**kwargs) -> BetaUserProfile` - -**post** `/v1/user_profiles/{id}` - -Update User Profile - -### Parameters - -- `id: str` - -- `external_id: Optional[str]` - -- `metadata: Optional[Dict[str, str]]` - - Key-value pairs to merge into the stored metadata. Keys provided overwrite existing values. To remove a key, set its value to an empty string. Keys not provided are left unchanged. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. - -- `betas: Optional[List[AnthropicBetaParam]]` - - Optional header to specify the beta version(s) you want to use. - - - `str` - - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `class BetaUserProfile: …` - - - `id: str` - - - `created_at: datetime` - - A timestamp in RFC 3339 format - - - `metadata: Dict[str, str]` - - - `trust_grants: Dict[str, BetaUserProfileTrustGrant]` - - - `status: str` - - - `type: str` - - - `updated_at: datetime` - - A timestamp in RFC 3339 format - - - `external_id: Optional[str]` - -### Example - -```python -import os -from anthropic import Anthropic - -client = Anthropic( - api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted -) -beta_user_profile = client.beta.user_profiles.update( - id="id", -) -print(beta_user_profile.id) -``` - -## Create Enrollment URL - -`beta.user_profiles.create_enrollment_url(strid, UserProfileCreateEnrollmentURLParams**kwargs) -> BetaUserProfileEnrollmentURL` - -**post** `/v1/user_profiles/{id}/enrollment_url` - -Create Enrollment URL - -### Parameters - -- `id: str` - -- `betas: Optional[List[AnthropicBetaParam]]` - - Optional header to specify the beta version(s) you want to use. - - - `str` - - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `class BetaUserProfileEnrollmentURL: …` - - - `expires_at: datetime` - - A timestamp in RFC 3339 format - - - `type: str` - - - `url: str` - -### Example - -```python -import os -from anthropic import Anthropic - -client = Anthropic( - api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted -) -beta_user_profile_enrollment_url = client.beta.user_profiles.create_enrollment_url( - id="id", -) -print(beta_user_profile_enrollment_url.expires_at) -``` - -## Domain Types - -### Beta User Profile - -- `class BetaUserProfile: …` - - - `id: str` - - - `created_at: datetime` - - A timestamp in RFC 3339 format - - - `metadata: Dict[str, str]` - - - `trust_grants: Dict[str, BetaUserProfileTrustGrant]` - - - `status: str` - - - `type: str` - - - `updated_at: datetime` - - A timestamp in RFC 3339 format - - - `external_id: Optional[str]` - -### Beta User Profile Enrollment URL - -- `class BetaUserProfileEnrollmentURL: …` - - - `expires_at: datetime` - - A timestamp in RFC 3339 format - - - `type: str` - - - `url: str` - -### Beta User Profile Trust Grant - -- `class BetaUserProfileTrustGrant: …` - - - `status: str` diff --git a/content/en/api/python/beta/agents.md b/content/en/api/python/beta/agents.md new file mode 100644 index 000000000..8efc76839 --- /dev/null +++ b/content/en/api/python/beta/agents.md @@ -0,0 +1,4433 @@ +# Agents + +## Create + +`beta.agents.create(AgentCreateParams**kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `model: Model` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `Union[Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more], str]` + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `class BetaManagedAgentsModelConfigParams: …` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +- `name: str` + + Human-readable name for the agent. 1-256 characters. + +- `description: Optional[str]` + + Description of what the agent does. Up to 2048 characters. + +- `mcp_servers: Optional[Iterable[BetaManagedAgentsURLMCPServerParams]]` + + MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `name: str` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + Endpoint URL for the MCP server. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + +- `skills: Optional[Iterable[BetaManagedAgentsSkillParams]]` + + Skills available to the agent. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams: …` + + An Anthropic-managed skill. + + - `skill_id: str` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams: …` + + A user-created custom skill. + + - `skill_id: str` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + +- `system: Optional[str]` + + System prompt for the agent. Up to 100,000 characters. + +- `tools: Optional[Iterable[Tool]]` + + Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params: …` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `configs: Optional[List[BetaManagedAgentsAgentToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: Optional[bool]` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsAgentToolsetDefaultConfigParams]` + + Default configuration for all tools in a toolset. + + - `enabled: Optional[bool]` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `class BetaManagedAgentsMCPToolsetParams: …` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: str` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `configs: Optional[List[BetaManagedAgentsMCPToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: str` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: Optional[bool]` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsMCPToolsetDefaultConfigParams]` + + Default configuration for all tools from an MCP server. + + - `enabled: Optional[bool]` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `class BetaManagedAgentsCustomToolParams: …` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: str` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: Literal["custom"]` + + - `"custom"` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_agent = client.beta.agents.create( + model="claude-sonnet-4-6", + name="My First Agent", +) +print(beta_managed_agents_agent.id) +``` + +## List + +`beta.agents.list(AgentListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsAgent]` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `created_at_gte: Optional[Union[str, datetime]]` + + Return agents created at or after this time (inclusive). + +- `created_at_lte: Optional[Union[str, datetime]]` + + Return agents created at or before this time (inclusive). + +- `include_archived: Optional[bool]` + + Include archived agents in results. Defaults to false. + +- `limit: Optional[int]` + + Maximum results per page. Default 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination cursor from a previous response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.agents.list() +page = page.data[0] +print(page.id) +``` + +## Retrieve + +`beta.agents.retrieve(stragent_id, AgentRetrieveParams**kwargs) -> BetaManagedAgentsAgent` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `agent_id: str` + +- `version: Optional[int]` + + Agent version. Omit for the most recent version. Must be at least 1 if specified. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_agent = client.beta.agents.retrieve( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", +) +print(beta_managed_agents_agent.id) +``` + +## Update + +`beta.agents.update(stragent_id, AgentUpdateParams**kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `agent_id: str` + +- `version: int` + + The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + +- `description: Optional[str]` + + Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + +- `mcp_servers: Optional[Iterable[BetaManagedAgentsURLMCPServerParams]]` + + MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `name: str` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + Endpoint URL for the MCP server. + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + +- `model: Optional[Model]` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `Union[Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more], str]` + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `class BetaManagedAgentsModelConfigParams: …` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +- `name: Optional[str]` + + Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + +- `skills: Optional[Iterable[BetaManagedAgentsSkillParams]]` + + Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams: …` + + An Anthropic-managed skill. + + - `skill_id: str` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams: …` + + A user-created custom skill. + + - `skill_id: str` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + +- `system: Optional[str]` + + System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + +- `tools: Optional[Iterable[Tool]]` + + Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params: …` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `configs: Optional[List[BetaManagedAgentsAgentToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: Optional[bool]` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsAgentToolsetDefaultConfigParams]` + + Default configuration for all tools in a toolset. + + - `enabled: Optional[bool]` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `class BetaManagedAgentsMCPToolsetParams: …` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: str` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `configs: Optional[List[BetaManagedAgentsMCPToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: str` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: Optional[bool]` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsMCPToolsetDefaultConfigParams]` + + Default configuration for all tools from an MCP server. + + - `enabled: Optional[bool]` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `class BetaManagedAgentsCustomToolParams: …` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: str` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: Literal["custom"]` + + - `"custom"` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_agent = client.beta.agents.update( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", + version=1, +) +print(beta_managed_agents_agent.id) +``` + +## Archive + +`beta.agents.archive(stragent_id, AgentArchiveParams**kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `agent_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_agent = client.beta.agents.archive( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", +) +print(beta_managed_agents_agent.id) +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `class BetaManagedAgentsAgentToolConfig: …` + + Configuration for a specific agent tool. + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Agent Tool Config Params + +- `class BetaManagedAgentsAgentToolConfigParams: …` + + Configuration override for a specific tool within a toolset. + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: Optional[bool]` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config + +- `class BetaManagedAgentsAgentToolsetDefaultConfig: …` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `class BetaManagedAgentsAgentToolsetDefaultConfigParams: …` + + Default configuration for all tools in a toolset. + + - `enabled: Optional[bool]` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset20260401 + +- `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `class BetaManagedAgentsAgentToolset20260401Params: …` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `configs: Optional[List[BetaManagedAgentsAgentToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: Optional[bool]` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsAgentToolsetDefaultConfigParams]` + + Default configuration for all tools in a toolset. + + - `enabled: Optional[bool]` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Always Allow Policy + +- `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + +### Beta Managed Agents Always Ask Policy + +- `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Anthropic Skill + +- `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + +### Beta Managed Agents Anthropic Skill Params + +- `class BetaManagedAgentsAnthropicSkillParams: …` + + An Anthropic-managed skill. + + - `skill_id: str` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + +### Beta Managed Agents Custom Skill Params + +- `class BetaManagedAgentsCustomSkillParams: …` + + A user-created custom skill. + + - `skill_id: str` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + +### Beta Managed Agents Custom Tool Input Schema + +- `class BetaManagedAgentsCustomToolInputSchema: …` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + +### Beta Managed Agents Custom Tool Params + +- `class BetaManagedAgentsCustomToolParams: …` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: str` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: Literal["custom"]` + + - `"custom"` + +### Beta Managed Agents MCP Server URL Definition + +- `class BetaManagedAgentsMCPServerURLDefinition: …` + + URL-based MCP server connection as returned in API responses. + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + +### Beta Managed Agents MCP Tool Config + +- `class BetaManagedAgentsMCPToolConfig: …` + + Resolved configuration for a specific MCP tool. + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents MCP Tool Config Params + +- `class BetaManagedAgentsMCPToolConfigParams: …` + + Configuration override for a specific MCP tool. + + - `name: str` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: Optional[bool]` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset + +- `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + +### Beta Managed Agents MCP Toolset Default Config + +- `class BetaManagedAgentsMCPToolsetDefaultConfig: …` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `class BetaManagedAgentsMCPToolsetDefaultConfigParams: …` + + Default configuration for all tools from an MCP server. + + - `enabled: Optional[bool]` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Params + +- `class BetaManagedAgentsMCPToolsetParams: …` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: str` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `configs: Optional[List[BetaManagedAgentsMCPToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: str` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: Optional[bool]` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsMCPToolsetDefaultConfigParams]` + + Default configuration for all tools from an MCP server. + + - `enabled: Optional[bool]` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + +### Beta Managed Agents Model + +- `Union[Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more], str]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + +### Beta Managed Agents Model Config + +- `class BetaManagedAgentsModelConfig: …` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Model Config Params + +- `class BetaManagedAgentsModelConfigParams: …` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Skill Params + +- `BetaManagedAgentsSkillParams` + + Skill to load in the session container. + + - `class BetaManagedAgentsAnthropicSkillParams: …` + + An Anthropic-managed skill. + + - `skill_id: str` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams: …` + + A user-created custom skill. + + - `skill_id: str` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `class BetaManagedAgentsURLMCPServerParams: …` + + URL-based MCP server connection. + + - `name: str` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + Endpoint URL for the MCP server. + +# Versions + +## List + +`beta.agents.versions.list(stragent_id, VersionListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsAgent]` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agent_id: str` + +- `limit: Optional[int]` + + Maximum results per page. Default 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination cursor. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.agents.versions.list( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", +) +page = page.data[0] +print(page.id) +``` diff --git a/content/en/api/python/beta/agents/archive.md b/content/en/api/python/beta/agents/archive.md new file mode 100644 index 000000000..b3df1e996 --- /dev/null +++ b/content/en/api/python/beta/agents/archive.md @@ -0,0 +1,383 @@ +## Archive + +`beta.agents.archive(stragent_id, AgentArchiveParams**kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `agent_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_agent = client.beta.agents.archive( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", +) +print(beta_managed_agents_agent.id) +``` diff --git a/content/en/api/python/beta/agents/create.md b/content/en/api/python/beta/agents/create.md new file mode 100644 index 000000000..16dceded3 --- /dev/null +++ b/content/en/api/python/beta/agents/create.md @@ -0,0 +1,766 @@ +## Create + +`beta.agents.create(AgentCreateParams**kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `model: Model` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `Union[Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more], str]` + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `class BetaManagedAgentsModelConfigParams: …` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +- `name: str` + + Human-readable name for the agent. 1-256 characters. + +- `description: Optional[str]` + + Description of what the agent does. Up to 2048 characters. + +- `mcp_servers: Optional[Iterable[BetaManagedAgentsURLMCPServerParams]]` + + MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `name: str` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + Endpoint URL for the MCP server. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + +- `skills: Optional[Iterable[BetaManagedAgentsSkillParams]]` + + Skills available to the agent. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams: …` + + An Anthropic-managed skill. + + - `skill_id: str` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams: …` + + A user-created custom skill. + + - `skill_id: str` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + +- `system: Optional[str]` + + System prompt for the agent. Up to 100,000 characters. + +- `tools: Optional[Iterable[Tool]]` + + Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params: …` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `configs: Optional[List[BetaManagedAgentsAgentToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: Optional[bool]` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsAgentToolsetDefaultConfigParams]` + + Default configuration for all tools in a toolset. + + - `enabled: Optional[bool]` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `class BetaManagedAgentsMCPToolsetParams: …` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: str` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `configs: Optional[List[BetaManagedAgentsMCPToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: str` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: Optional[bool]` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsMCPToolsetDefaultConfigParams]` + + Default configuration for all tools from an MCP server. + + - `enabled: Optional[bool]` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `class BetaManagedAgentsCustomToolParams: …` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: str` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: Literal["custom"]` + + - `"custom"` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_agent = client.beta.agents.create( + model="claude-sonnet-4-6", + name="My First Agent", +) +print(beta_managed_agents_agent.id) +``` diff --git a/content/en/api/python/beta/agents/list.md b/content/en/api/python/beta/agents/list.md new file mode 100644 index 000000000..cb81e777f --- /dev/null +++ b/content/en/api/python/beta/agents/list.md @@ -0,0 +1,400 @@ +## List + +`beta.agents.list(AgentListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsAgent]` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `created_at_gte: Optional[Union[str, datetime]]` + + Return agents created at or after this time (inclusive). + +- `created_at_lte: Optional[Union[str, datetime]]` + + Return agents created at or before this time (inclusive). + +- `include_archived: Optional[bool]` + + Include archived agents in results. Defaults to false. + +- `limit: Optional[int]` + + Maximum results per page. Default 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination cursor from a previous response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.agents.list() +page = page.data[0] +print(page.id) +``` diff --git a/content/en/api/python/beta/agents/retrieve.md b/content/en/api/python/beta/agents/retrieve.md new file mode 100644 index 000000000..6be095d1e --- /dev/null +++ b/content/en/api/python/beta/agents/retrieve.md @@ -0,0 +1,387 @@ +## Retrieve + +`beta.agents.retrieve(stragent_id, AgentRetrieveParams**kwargs) -> BetaManagedAgentsAgent` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `agent_id: str` + +- `version: Optional[int]` + + Agent version. Omit for the most recent version. Must be at least 1 if specified. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_agent = client.beta.agents.retrieve( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", +) +print(beta_managed_agents_agent.id) +``` diff --git a/content/en/api/python/beta/agents/update.md b/content/en/api/python/beta/agents/update.md new file mode 100644 index 000000000..5617f6771 --- /dev/null +++ b/content/en/api/python/beta/agents/update.md @@ -0,0 +1,772 @@ +## Update + +`beta.agents.update(stragent_id, AgentUpdateParams**kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `agent_id: str` + +- `version: int` + + The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + +- `description: Optional[str]` + + Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + +- `mcp_servers: Optional[Iterable[BetaManagedAgentsURLMCPServerParams]]` + + MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `name: str` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + Endpoint URL for the MCP server. + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + +- `model: Optional[Model]` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `Union[Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more], str]` + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `class BetaManagedAgentsModelConfigParams: …` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +- `name: Optional[str]` + + Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + +- `skills: Optional[Iterable[BetaManagedAgentsSkillParams]]` + + Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams: …` + + An Anthropic-managed skill. + + - `skill_id: str` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams: …` + + A user-created custom skill. + + - `skill_id: str` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: Optional[str]` + + Version to pin. Defaults to latest if omitted. + +- `system: Optional[str]` + + System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + +- `tools: Optional[Iterable[Tool]]` + + Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params: …` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `configs: Optional[List[BetaManagedAgentsAgentToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled: Optional[bool]` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsAgentToolsetDefaultConfigParams]` + + Default configuration for all tools in a toolset. + + - `enabled: Optional[bool]` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `class BetaManagedAgentsMCPToolsetParams: …` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: str` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `configs: Optional[List[BetaManagedAgentsMCPToolConfigParams]]` + + Per-tool configuration overrides. + + - `name: str` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: Optional[bool]` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: Optional[BetaManagedAgentsMCPToolsetDefaultConfigParams]` + + Default configuration for all tools from an MCP server. + + - `enabled: Optional[bool]` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: Optional[PermissionPolicy]` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `class BetaManagedAgentsCustomToolParams: …` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: str` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: Literal["custom"]` + + - `"custom"` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_agent = client.beta.agents.update( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", + version=1, +) +print(beta_managed_agents_agent.id) +``` diff --git a/content/en/api/python/beta/agents/versions.md b/content/en/api/python/beta/agents/versions.md new file mode 100644 index 000000000..b9907b029 --- /dev/null +++ b/content/en/api/python/beta/agents/versions.md @@ -0,0 +1,394 @@ +# Versions + +## List + +`beta.agents.versions.list(stragent_id, VersionListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsAgent]` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agent_id: str` + +- `limit: Optional[int]` + + Maximum results per page. Default 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination cursor. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.agents.versions.list( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", +) +page = page.data[0] +print(page.id) +``` diff --git a/content/en/api/python/beta/agents/versions/list.md b/content/en/api/python/beta/agents/versions/list.md new file mode 100644 index 000000000..5233863c9 --- /dev/null +++ b/content/en/api/python/beta/agents/versions/list.md @@ -0,0 +1,392 @@ +## List + +`beta.agents.versions.list(stragent_id, VersionListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsAgent]` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agent_id: str` + +- `limit: Optional[int]` + + Maximum results per page. Default 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination cursor. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent: …` + + A Managed Agents `agent`. + + - `id: str` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `metadata: Dict[str, str]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `version: int` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.agents.versions.list( + agent_id="agent_011CZkYpogX7uDKUyvBTophP", +) +page = page.data[0] +print(page.id) +``` diff --git a/content/en/api/python/beta/environments.md b/content/en/api/python/beta/environments.md new file mode 100644 index 000000000..c300e8a40 --- /dev/null +++ b/content/en/api/python/beta/environments.md @@ -0,0 +1,1733 @@ +# Environments + +## Create + +`beta.environments.create(EnvironmentCreateParams**kwargs) -> BetaEnvironment` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `name: str` + + Human-readable name for the environment + +- `config: Optional[BetaCloudConfigParams]` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `networking: Optional[Networking]` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetworkParams: …` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: Optional[bool]` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: Optional[bool]` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Optional[List[str]]` + + Specifies domains the container can reach. + + - `packages: Optional[BetaPackagesParams]` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Optional[List[str]]` + + Ubuntu/Debian packages to install + + - `cargo: Optional[List[str]]` + + Rust packages to install + + - `gem: Optional[List[str]]` + + Ruby packages to install + + - `go: Optional[List[str]]` + + Go packages to install + + - `npm: Optional[List[str]]` + + Node.js packages to install + + - `pip: Optional[List[str]]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + +- `description: Optional[str]` + + Optional description of the environment + +- `metadata: Optional[Dict[str, str]]` + + User-provided metadata key-value pairs + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment = client.beta.environments.create( + name="python-data-analysis", +) +print(beta_environment.id) +``` + +## List + +`beta.environments.list(EnvironmentListParams**kwargs) -> SyncPageCursor[BetaEnvironment]` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `include_archived: Optional[bool]` + + Include archived environments in the response + +- `limit: Optional[int]` + + Maximum number of environments to return + +- `page: Optional[str]` + + Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.environments.list() +page = page.data[0] +print(page.id) +``` + +## Retrieve + +`beta.environments.retrieve(strenvironment_id, EnvironmentRetrieveParams**kwargs) -> BetaEnvironment` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `environment_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment = client.beta.environments.retrieve( + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_environment.id) +``` + +## Update + +`beta.environments.update(strenvironment_id, EnvironmentUpdateParams**kwargs) -> BetaEnvironment` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `environment_id: str` + +- `config: Optional[BetaCloudConfigParams]` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `networking: Optional[Networking]` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetworkParams: …` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: Optional[bool]` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: Optional[bool]` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Optional[List[str]]` + + Specifies domains the container can reach. + + - `packages: Optional[BetaPackagesParams]` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Optional[List[str]]` + + Ubuntu/Debian packages to install + + - `cargo: Optional[List[str]]` + + Rust packages to install + + - `gem: Optional[List[str]]` + + Ruby packages to install + + - `go: Optional[List[str]]` + + Go packages to install + + - `npm: Optional[List[str]]` + + Node.js packages to install + + - `pip: Optional[List[str]]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + +- `description: Optional[str]` + + Updated description of the environment + +- `metadata: Optional[Dict[str, Optional[str]]]` + + User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + +- `name: Optional[str]` + + Updated name for the environment + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment = client.beta.environments.update( + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_environment.id) +``` + +## Delete + +`beta.environments.delete(strenvironment_id, EnvironmentDeleteParams**kwargs) -> BetaEnvironmentDeleteResponse` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `environment_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironmentDeleteResponse: …` + + Response after deleting an environment. + + - `id: str` + + Environment identifier + + - `type: Literal["environment_deleted"]` + + The type of response + + - `"environment_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment_delete_response = client.beta.environments.delete( + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_environment_delete_response.id) +``` + +## Archive + +`beta.environments.archive(strenvironment_id, EnvironmentArchiveParams**kwargs) -> BetaEnvironment` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `environment_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment = client.beta.environments.archive( + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_environment.id) +``` + +## Domain Types + +### Beta Cloud Config + +- `class BetaCloudConfig: …` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + +### Beta Cloud Config Params + +- `class BetaCloudConfigParams: …` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `networking: Optional[Networking]` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetworkParams: …` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: Optional[bool]` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: Optional[bool]` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Optional[List[str]]` + + Specifies domains the container can reach. + + - `packages: Optional[BetaPackagesParams]` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Optional[List[str]]` + + Ubuntu/Debian packages to install + + - `cargo: Optional[List[str]]` + + Rust packages to install + + - `gem: Optional[List[str]]` + + Ruby packages to install + + - `go: Optional[List[str]]` + + Go packages to install + + - `npm: Optional[List[str]]` + + Node.js packages to install + + - `pip: Optional[List[str]]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + +### Beta Environment + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `class BetaEnvironmentDeleteResponse: …` + + Response after deleting an environment. + + - `id: str` + + Environment identifier + + - `type: Literal["environment_deleted"]` + + The type of response + + - `"environment_deleted"` + +### Beta Limited Network + +- `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + +### Beta Limited Network Params + +- `class BetaLimitedNetworkParams: …` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: Optional[bool]` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: Optional[bool]` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Optional[List[str]]` + + Specifies domains the container can reach. + +### Beta Packages + +- `class BetaPackages: …` + + Packages (and their versions) available in this environment. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + +### Beta Packages Params + +- `class BetaPackagesParams: …` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Optional[List[str]]` + + Ubuntu/Debian packages to install + + - `cargo: Optional[List[str]]` + + Rust packages to install + + - `gem: Optional[List[str]]` + + Ruby packages to install + + - `go: Optional[List[str]]` + + Go packages to install + + - `npm: Optional[List[str]]` + + Node.js packages to install + + - `pip: Optional[List[str]]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + +### Beta Unrestricted Network + +- `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` diff --git a/content/en/api/python/beta/environments/archive.md b/content/en/api/python/beta/environments/archive.md new file mode 100644 index 000000000..ee5469728 --- /dev/null +++ b/content/en/api/python/beta/environments/archive.md @@ -0,0 +1,196 @@ +## Archive + +`beta.environments.archive(strenvironment_id, EnvironmentArchiveParams**kwargs) -> BetaEnvironment` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `environment_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment = client.beta.environments.archive( + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_environment.id) +``` diff --git a/content/en/api/python/beta/environments/create.md b/content/en/api/python/beta/environments/create.md new file mode 100644 index 000000000..42aa11a0f --- /dev/null +++ b/content/en/api/python/beta/environments/create.md @@ -0,0 +1,294 @@ +## Create + +`beta.environments.create(EnvironmentCreateParams**kwargs) -> BetaEnvironment` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `name: str` + + Human-readable name for the environment + +- `config: Optional[BetaCloudConfigParams]` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `networking: Optional[Networking]` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetworkParams: …` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: Optional[bool]` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: Optional[bool]` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Optional[List[str]]` + + Specifies domains the container can reach. + + - `packages: Optional[BetaPackagesParams]` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Optional[List[str]]` + + Ubuntu/Debian packages to install + + - `cargo: Optional[List[str]]` + + Rust packages to install + + - `gem: Optional[List[str]]` + + Ruby packages to install + + - `go: Optional[List[str]]` + + Go packages to install + + - `npm: Optional[List[str]]` + + Node.js packages to install + + - `pip: Optional[List[str]]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + +- `description: Optional[str]` + + Optional description of the environment + +- `metadata: Optional[Dict[str, str]]` + + User-provided metadata key-value pairs + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment = client.beta.environments.create( + name="python-data-analysis", +) +print(beta_environment.id) +``` diff --git a/content/en/api/python/beta/environments/delete.md b/content/en/api/python/beta/environments/delete.md new file mode 100644 index 000000000..c891550ca --- /dev/null +++ b/content/en/api/python/beta/environments/delete.md @@ -0,0 +1,92 @@ +## Delete + +`beta.environments.delete(strenvironment_id, EnvironmentDeleteParams**kwargs) -> BetaEnvironmentDeleteResponse` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `environment_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironmentDeleteResponse: …` + + Response after deleting an environment. + + - `id: str` + + Environment identifier + + - `type: Literal["environment_deleted"]` + + The type of response + + - `"environment_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment_delete_response = client.beta.environments.delete( + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_environment_delete_response.id) +``` diff --git a/content/en/api/python/beta/environments/list.md b/content/en/api/python/beta/environments/list.md new file mode 100644 index 000000000..ff23b51c6 --- /dev/null +++ b/content/en/api/python/beta/environments/list.md @@ -0,0 +1,205 @@ +## List + +`beta.environments.list(EnvironmentListParams**kwargs) -> SyncPageCursor[BetaEnvironment]` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `include_archived: Optional[bool]` + + Include archived environments in the response + +- `limit: Optional[int]` + + Maximum number of environments to return + +- `page: Optional[str]` + + Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.environments.list() +page = page.data[0] +print(page.id) +``` diff --git a/content/en/api/python/beta/environments/retrieve.md b/content/en/api/python/beta/environments/retrieve.md new file mode 100644 index 000000000..249938dad --- /dev/null +++ b/content/en/api/python/beta/environments/retrieve.md @@ -0,0 +1,196 @@ +## Retrieve + +`beta.environments.retrieve(strenvironment_id, EnvironmentRetrieveParams**kwargs) -> BetaEnvironment` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `environment_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment = client.beta.environments.retrieve( + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_environment.id) +``` diff --git a/content/en/api/python/beta/environments/update.md b/content/en/api/python/beta/environments/update.md new file mode 100644 index 000000000..4a076bf52 --- /dev/null +++ b/content/en/api/python/beta/environments/update.md @@ -0,0 +1,296 @@ +## Update + +`beta.environments.update(strenvironment_id, EnvironmentUpdateParams**kwargs) -> BetaEnvironment` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `environment_id: str` + +- `config: Optional[BetaCloudConfigParams]` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `networking: Optional[Networking]` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetworkParams: …` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers: Optional[bool]` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: Optional[bool]` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Optional[List[str]]` + + Specifies domains the container can reach. + + - `packages: Optional[BetaPackagesParams]` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Optional[List[str]]` + + Ubuntu/Debian packages to install + + - `cargo: Optional[List[str]]` + + Rust packages to install + + - `gem: Optional[List[str]]` + + Ruby packages to install + + - `go: Optional[List[str]]` + + Go packages to install + + - `npm: Optional[List[str]]` + + Node.js packages to install + + - `pip: Optional[List[str]]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + +- `description: Optional[str]` + + Updated description of the environment + +- `metadata: Optional[Dict[str, Optional[str]]]` + + User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + +- `name: Optional[str]` + + Updated name for the environment + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment: …` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: str` + + Environment identifier (e.g., 'env_...') + + - `archived_at: Optional[str]` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: Networking` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork: …` + + Unrestricted network access. + + - `type: Literal["unrestricted"]` + + Network policy type + + - `"unrestricted"` + + - `class BetaLimitedNetwork: …` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: List[str]` + + Specifies domains the container can reach. + + - `type: Literal["limited"]` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: List[str]` + + Ubuntu/Debian packages to install + + - `cargo: List[str]` + + Rust packages to install + + - `gem: List[str]` + + Ruby packages to install + + - `go: List[str]` + + Go packages to install + + - `npm: List[str]` + + Node.js packages to install + + - `pip: List[str]` + + Python packages to install + + - `type: Optional[Literal["packages"]]` + + Package configuration type + + - `"packages"` + + - `type: Literal["cloud"]` + + Environment type + + - `"cloud"` + + - `created_at: str` + + RFC 3339 timestamp when environment was created + + - `description: str` + + User-provided description for the environment + + - `metadata: Dict[str, str]` + + User-provided metadata key-value pairs + + - `name: str` + + Human-readable name for the environment + + - `type: Literal["environment"]` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: str` + + RFC 3339 timestamp when environment was last updated + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_environment = client.beta.environments.update( + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_environment.id) +``` diff --git a/content/en/api/python/beta/files.md b/content/en/api/python/beta/files.md index 7a53c8bea..ebbd10e22 100644 --- a/content/en/api/python/beta/files.md +++ b/content/en/api/python/beta/files.md @@ -20,7 +20,7 @@ Upload File - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Upload File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata: …` @@ -104,6 +102,20 @@ Upload File Whether the file can be downloaded. + - `scope: Optional[BetaFileScope]` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```python @@ -143,13 +155,17 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. +- `scope_id: Optional[str]` + + Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `betas: Optional[List[AnthropicBetaParam]]` Optional header to specify the beta version(s) you want to use. - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -193,8 +209,6 @@ List Files - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata: …` @@ -233,6 +247,20 @@ List Files Whether the file can be downloaded. + - `scope: Optional[BetaFileScope]` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```python @@ -267,7 +295,7 @@ Download File - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -311,8 +339,6 @@ Download File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BinaryResponseContent` @@ -354,7 +380,7 @@ Get File Metadata - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -398,8 +424,6 @@ Get File Metadata - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata: …` @@ -438,6 +462,20 @@ Get File Metadata Whether the file can be downloaded. + - `scope: Optional[BetaFileScope]` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```python @@ -473,7 +511,7 @@ Delete File - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -517,8 +555,6 @@ Delete File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class DeletedFile: …` @@ -552,6 +588,20 @@ print(deleted_file.id) ## Domain Types +### Beta File Scope + +- `class BetaFileScope: …` + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Deleted File - `class DeletedFile: …` @@ -605,3 +655,17 @@ print(deleted_file.id) - `downloadable: Optional[bool]` Whether the file can be downloaded. + + - `scope: Optional[BetaFileScope]` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` diff --git a/content/en/api/python/beta/files/delete.md b/content/en/api/python/beta/files/delete.md index e0f38f11b..210800842 100644 --- a/content/en/api/python/beta/files/delete.md +++ b/content/en/api/python/beta/files/delete.md @@ -18,7 +18,7 @@ Delete File - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Delete File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class DeletedFile: …` diff --git a/content/en/api/python/beta/files/download.md b/content/en/api/python/beta/files/download.md index 6b9a71149..68744f8a7 100644 --- a/content/en/api/python/beta/files/download.md +++ b/content/en/api/python/beta/files/download.md @@ -18,7 +18,7 @@ Download File - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Download File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BinaryResponseContent` diff --git a/content/en/api/python/beta/files/list.md b/content/en/api/python/beta/files/list.md index 386ede2d4..ebb796a0f 100644 --- a/content/en/api/python/beta/files/list.md +++ b/content/en/api/python/beta/files/list.md @@ -22,13 +22,17 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. +- `scope_id: Optional[str]` + + Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `betas: Optional[List[AnthropicBetaParam]]` Optional header to specify the beta version(s) you want to use. - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -72,8 +76,6 @@ List Files - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata: …` @@ -112,6 +114,20 @@ List Files Whether the file can be downloaded. + - `scope: Optional[BetaFileScope]` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```python diff --git a/content/en/api/python/beta/files/retrieve_metadata.md b/content/en/api/python/beta/files/retrieve_metadata.md index 2efa97ff7..10377ed16 100644 --- a/content/en/api/python/beta/files/retrieve_metadata.md +++ b/content/en/api/python/beta/files/retrieve_metadata.md @@ -18,7 +18,7 @@ Get File Metadata - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Get File Metadata - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata: …` @@ -102,6 +100,20 @@ Get File Metadata Whether the file can be downloaded. + - `scope: Optional[BetaFileScope]` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```python diff --git a/content/en/api/python/beta/files/upload.md b/content/en/api/python/beta/files/upload.md index 82e21b347..e289478f9 100644 --- a/content/en/api/python/beta/files/upload.md +++ b/content/en/api/python/beta/files/upload.md @@ -18,7 +18,7 @@ Upload File - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Upload File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata: …` @@ -102,6 +100,20 @@ Upload File Whether the file can be downloaded. + - `scope: Optional[BetaFileScope]` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: str` + + The ID of the scoping resource (e.g., the session ID). + + - `type: Literal["session"]` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```python diff --git a/content/en/api/python/beta/messages.md b/content/en/api/python/beta/messages.md index 393952bcb..25cd61c37 100644 --- a/content/en/api/python/beta/messages.md +++ b/content/en/api/python/beta/messages.md @@ -2599,13 +2599,14 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -2621,9 +2622,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4694,17 +4699,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. -- `user_profile_id: Optional[str]` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Optional[List[AnthropicBetaParam]]` Optional header to specify the beta version(s) you want to use. - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -4748,8 +4749,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessage: …` @@ -5673,13 +5672,14 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -5695,9 +5695,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -8605,13 +8609,14 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -8627,9 +8632,13 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -10608,7 +10617,7 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -10652,8 +10661,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageTokensCount: …` @@ -10684,7 +10691,7 @@ beta_message_tokens_count = client.beta.messages.count_tokens( "content": "string", "role": "user", }], - model="claude-opus-4-6", + model="claude-mythos-preview", ) print(beta_message_tokens_count.context_management) ``` @@ -17874,13 +17881,14 @@ print(beta_message_tokens_count.context_management) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -17896,9 +17904,13 @@ print(beta_message_tokens_count.context_management) - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -23234,13 +23246,14 @@ print(beta_message_tokens_count.context_management) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -23256,9 +23269,13 @@ print(beta_message_tokens_count.context_management) - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -24494,13 +24511,14 @@ print(beta_message_tokens_count.context_management) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -24516,9 +24534,13 @@ print(beta_message_tokens_count.context_management) - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -35650,13 +35672,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -35672,9 +35695,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -37743,17 +37770,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id: Optional[str]` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Optional[List[AnthropicBetaParam]]` Optional header to specify the beta version(s) you want to use. - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -37797,8 +37820,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` @@ -37936,7 +37957,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -37980,8 +38001,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` @@ -38119,7 +38138,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -38163,8 +38182,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` @@ -38293,7 +38310,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -38337,8 +38354,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` @@ -38468,7 +38483,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -38512,8 +38527,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaDeletedMessageBatch: …` @@ -38569,7 +38582,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -38613,8 +38626,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatchIndividualResponse: …` @@ -39556,13 +39567,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -39578,9 +39590,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -41151,13 +41167,14 @@ for batch in client.beta.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -41173,9 +41190,13 @@ for batch in client.beta.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -42539,13 +42560,14 @@ for batch in client.beta.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -42561,9 +42583,13 @@ for batch in client.beta.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -43889,13 +43915,14 @@ for batch in client.beta.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -43911,9 +43938,13 @@ for batch in client.beta.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/python/beta/messages/batches.md b/content/en/api/python/beta/messages/batches.md index 61f3405ce..c08c50315 100644 --- a/content/en/api/python/beta/messages/batches.md +++ b/content/en/api/python/beta/messages/batches.md @@ -2615,13 +2615,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -2637,9 +2638,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4708,17 +4713,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id: Optional[str]` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Optional[List[AnthropicBetaParam]]` Optional header to specify the beta version(s) you want to use. - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -4762,8 +4763,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` @@ -4901,7 +4900,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -4945,8 +4944,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` @@ -5084,7 +5081,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -5128,8 +5125,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` @@ -5258,7 +5253,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -5302,8 +5297,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` @@ -5433,7 +5426,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -5477,8 +5470,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaDeletedMessageBatch: …` @@ -5534,7 +5525,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -5578,8 +5569,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatchIndividualResponse: …` @@ -6521,13 +6510,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -6543,9 +6533,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -8116,13 +8110,14 @@ for batch in client.beta.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -8138,9 +8133,13 @@ for batch in client.beta.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -9504,13 +9503,14 @@ for batch in client.beta.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -9526,9 +9526,13 @@ for batch in client.beta.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -10854,13 +10858,14 @@ for batch in client.beta.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -10876,9 +10881,13 @@ for batch in client.beta.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/python/beta/messages/batches/cancel.md b/content/en/api/python/beta/messages/batches/cancel.md index c762c9d52..1ee41a3bc 100644 --- a/content/en/api/python/beta/messages/batches/cancel.md +++ b/content/en/api/python/beta/messages/batches/cancel.md @@ -22,7 +22,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` diff --git a/content/en/api/python/beta/messages/batches/create.md b/content/en/api/python/beta/messages/batches/create.md index a308fbf9c..8b90cacc0 100644 --- a/content/en/api/python/beta/messages/batches/create.md +++ b/content/en/api/python/beta/messages/batches/create.md @@ -2613,13 +2613,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -2635,9 +2636,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4706,17 +4711,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id: Optional[str]` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Optional[List[AnthropicBetaParam]]` Optional header to specify the beta version(s) you want to use. - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -4760,8 +4761,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` diff --git a/content/en/api/python/beta/messages/batches/delete.md b/content/en/api/python/beta/messages/batches/delete.md index c08d15b77..a61b1c7c0 100644 --- a/content/en/api/python/beta/messages/batches/delete.md +++ b/content/en/api/python/beta/messages/batches/delete.md @@ -22,7 +22,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaDeletedMessageBatch: …` diff --git a/content/en/api/python/beta/messages/batches/list.md b/content/en/api/python/beta/messages/batches/list.md index bacee2ce7..a1433cddd 100644 --- a/content/en/api/python/beta/messages/batches/list.md +++ b/content/en/api/python/beta/messages/batches/list.md @@ -30,7 +30,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` diff --git a/content/en/api/python/beta/messages/batches/results.md b/content/en/api/python/beta/messages/batches/results.md index 04a2ca1c2..11b2688cf 100644 --- a/content/en/api/python/beta/messages/batches/results.md +++ b/content/en/api/python/beta/messages/batches/results.md @@ -22,7 +22,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatchIndividualResponse: …` @@ -1009,13 +1007,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -1031,9 +1030,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/python/beta/messages/batches/retrieve.md b/content/en/api/python/beta/messages/batches/retrieve.md index f6183cf35..6333ff91f 100644 --- a/content/en/api/python/beta/messages/batches/retrieve.md +++ b/content/en/api/python/beta/messages/batches/retrieve.md @@ -20,7 +20,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch: …` diff --git a/content/en/api/python/beta/messages/count_tokens.md b/content/en/api/python/beta/messages/count_tokens.md index 8d99c229b..77926eb81 100644 --- a/content/en/api/python/beta/messages/count_tokens.md +++ b/content/en/api/python/beta/messages/count_tokens.md @@ -2589,13 +2589,14 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -2611,9 +2612,13 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4592,7 +4597,7 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -4636,8 +4641,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageTokensCount: …` @@ -4668,7 +4671,7 @@ beta_message_tokens_count = client.beta.messages.count_tokens( "content": "string", "role": "user", }], - model="claude-opus-4-6", + model="claude-mythos-preview", ) print(beta_message_tokens_count.context_management) ``` diff --git a/content/en/api/python/beta/messages/create.md b/content/en/api/python/beta/messages/create.md index 24804ac63..53a50065b 100644 --- a/content/en/api/python/beta/messages/create.md +++ b/content/en/api/python/beta/messages/create.md @@ -2597,13 +2597,14 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -2619,9 +2620,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4692,17 +4697,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. -- `user_profile_id: Optional[str]` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Optional[List[AnthropicBetaParam]]` Optional header to specify the beta version(s) you want to use. - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -4746,8 +4747,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaMessage: …` @@ -5671,13 +5670,14 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -5693,9 +5693,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/python/beta/models.md b/content/en/api/python/beta/models.md index 075f95f84..54de58a6b 100644 --- a/content/en/api/python/beta/models.md +++ b/content/en/api/python/beta/models.md @@ -32,7 +32,7 @@ The Models API response can be used to determine which models are available for - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -76,8 +76,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaModelInfo: …` @@ -298,7 +296,7 @@ The Models API response can be used to determine information about a specific mo - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -342,8 +340,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaModelInfo: …` diff --git a/content/en/api/python/beta/models/list.md b/content/en/api/python/beta/models/list.md index ebd2bf725..bf8d84fdb 100644 --- a/content/en/api/python/beta/models/list.md +++ b/content/en/api/python/beta/models/list.md @@ -30,7 +30,7 @@ The Models API response can be used to determine which models are available for - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaModelInfo: …` diff --git a/content/en/api/python/beta/models/retrieve.md b/content/en/api/python/beta/models/retrieve.md index 0cde128e5..da2c05f1e 100644 --- a/content/en/api/python/beta/models/retrieve.md +++ b/content/en/api/python/beta/models/retrieve.md @@ -20,7 +20,7 @@ The Models API response can be used to determine information about a specific mo - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class BetaModelInfo: …` diff --git a/content/en/api/python/beta/sessions.md b/content/en/api/python/beta/sessions.md new file mode 100644 index 000000000..28663c8bc --- /dev/null +++ b/content/en/api/python/beta/sessions.md @@ -0,0 +1,14315 @@ +# Sessions + +## Create + +`beta.sessions.create(SessionCreateParams**kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `agent: Agent` + + Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `str` + + - `class BetaManagedAgentsAgentParams: …` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: str` + + The `agent` ID. + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: Optional[int]` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +- `environment_id: str` + + ID of the `environment` defining the container configuration for this session. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata attached to the session. + +- `resources: Optional[Iterable[Resource]]` + + Resources (e.g. repositories, files) to mount into the session's container. + + - `class BetaManagedAgentsGitHubRepositoryResourceParams: …` + + Mount a GitHub repository into the session's container. + + - `authorization_token: str` + + GitHub authorization token used to clone the repository. + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `url: str` + + Github URL of the repository + + - `checkout: Optional[Checkout]` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/workspace/`. + + - `class BetaManagedAgentsFileResourceParams: …` + + Mount a file uploaded via the Files API into the session. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `title: Optional[str]` + + Human-readable session title. + +- `vault_ids: Optional[Sequence[str]]` + + Vault IDs for stored credentials the agent can use during the session. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_session = client.beta.sessions.create( + agent="agent_011CZkYpogX7uDKUyvBTophP", + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_managed_agents_session.id) +``` + +## List + +`beta.sessions.list(SessionListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSession]` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `agent_id: Optional[str]` + + Filter sessions created with this agent ID. + +- `agent_version: Optional[int]` + + Filter by agent version. Only applies when agent_id is also set. + +- `created_at_gt: Optional[Union[str, datetime]]` + + Return sessions created after this time (exclusive). + +- `created_at_gte: Optional[Union[str, datetime]]` + + Return sessions created at or after this time (inclusive). + +- `created_at_lt: Optional[Union[str, datetime]]` + + Return sessions created before this time (exclusive). + +- `created_at_lte: Optional[Union[str, datetime]]` + + Return sessions created at or before this time (inclusive). + +- `include_archived: Optional[bool]` + + When true, includes archived sessions. Default: false (exclude archived). + +- `limit: Optional[int]` + + Maximum number of results to return. + +- `order: Optional[Literal["asc", "desc"]]` + + Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `"asc"` + + - `"desc"` + +- `page: Optional[str]` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.sessions.list() +page = page.data[0] +print(page.id) +``` + +## Retrieve + +`beta.sessions.retrieve(strsession_id, SessionRetrieveParams**kwargs) -> BetaManagedAgentsSession` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_session = client.beta.sessions.retrieve( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_session.id) +``` + +## Update + +`beta.sessions.update(strsession_id, SessionUpdateParams**kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `session_id: str` + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + +- `title: Optional[str]` + + Human-readable session title. + +- `vault_ids: Optional[Sequence[str]]` + + Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_session = client.beta.sessions.update( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_session.id) +``` + +## Delete + +`beta.sessions.delete(strsession_id, SessionDeleteParams**kwargs) -> BetaManagedAgentsDeletedSession` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedSession: …` + + Confirmation that a `session` has been permanently deleted. + + - `id: str` + + - `type: Literal["session_deleted"]` + + - `"session_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_deleted_session = client.beta.sessions.delete( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_deleted_session.id) +``` + +## Archive + +`beta.sessions.archive(strsession_id, SessionArchiveParams**kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_session = client.beta.sessions.archive( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_session.id) +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `class BetaManagedAgentsAgentParams: …` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: str` + + The `agent` ID. + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: Optional[int]` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + +### Beta Managed Agents Cache Creation Usage + +- `class BetaManagedAgentsCacheCreationUsage: …` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + +### Beta Managed Agents Deleted Session + +- `class BetaManagedAgentsDeletedSession: …` + + Confirmation that a `session` has been permanently deleted. + + - `id: str` + + - `type: Literal["session_deleted"]` + + - `"session_deleted"` + +### Beta Managed Agents File Resource Params + +- `class BetaManagedAgentsFileResourceParams: …` + + Mount a file uploaded via the Files API into the session. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `class BetaManagedAgentsGitHubRepositoryResourceParams: …` + + Mount a GitHub repository into the session's container. + + - `authorization_token: str` + + GitHub authorization token used to clone the repository. + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `url: str` + + Github URL of the repository + + - `checkout: Optional[Checkout]` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `class BetaManagedAgentsSessionAgent: …` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + +### Beta Managed Agents Session Stats + +- `class BetaManagedAgentsSessionStats: …` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `class BetaManagedAgentsSessionUsage: …` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + +# Events + +## List + +`beta.sessions.events.list(strsession_id, EventListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSessionEvent]` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `session_id: str` + +- `limit: Optional[int]` + + Query parameter for limit + +- `order: Optional[Literal["asc", "desc"]]` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"` + + - `"desc"` + +- `page: Optional[str]` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionEvent` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.sessions.events.list( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +page = page.data[0] +print(page) +``` + +## Send + +`beta.sessions.events.send(strsession_id, EventSendParams**kwargs) -> BetaManagedAgentsSendSessionEvents` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `session_id: str` + +- `events: Iterable[BetaManagedAgentsEventParams]` + + Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams: …` + + Parameters for sending a user message to the session. + + - `content: List[Content]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams: …` + + Parameters for sending an interrupt to pause the agent. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams: …` + + Parameters for confirming or denying a tool execution request. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams: …` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSendSessionEvents: …` + + Events that were successfully sent to the session. + + - `data: Optional[List[Data]]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_send_session_events = client.beta.sessions.events.send( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", + events=[{ + "content": [{ + "text": "Where is my order #1234?", + "type": "text", + }], + "type": "user.message", + }], +) +print(beta_managed_agents_send_session_events.data) +``` + +## Stream + +`beta.sessions.events.stream(strsession_id, EventStreamParams**kwargs) -> BetaManagedAgentsStreamSessionEvents` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +for event in client.beta.sessions.events.stream( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +): + print(event) +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Agent Message Event + +- `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Base64 Document Source + +- `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + +### Beta Managed Agents Base64 Image Source + +- `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + +### Beta Managed Agents Billing Error + +- `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + +### Beta Managed Agents Document Block + +- `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + +### Beta Managed Agents Event Params + +- `BetaManagedAgentsEventParams` + + Union type for event parameters that can be sent to a session. + + - `class BetaManagedAgentsUserMessageEventParams: …` + + Parameters for sending a user message to the session. + + - `content: List[Content]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams: …` + + Parameters for sending an interrupt to pause the agent. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams: …` + + Parameters for confirming or denying a tool execution request. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams: …` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + +### Beta Managed Agents File Image Source + +- `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + +### Beta Managed Agents Image Block + +- `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + +### Beta Managed Agents Retry Status Exhausted + +- `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + +### Beta Managed Agents Send Session Events + +- `class BetaManagedAgentsSendSessionEvents: …` + + Events that were successfully sent to the session. + + - `data: Optional[List[Data]]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + +### Beta Managed Agents Session Error Event + +- `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + +### Beta Managed Agents Session Event + +- `BetaManagedAgentsSessionEvent` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `class BetaManagedAgentsSpanModelUsage: …` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Stream Session Events + +- `BetaManagedAgentsStreamSessionEvents` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Beta Managed Agents Text Block + +- `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + +### Beta Managed Agents Unknown Error + +- `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + +### Beta Managed Agents URL Document Source + +- `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `class BetaManagedAgentsUserCustomToolResultEventParams: …` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `class BetaManagedAgentsUserInterruptEventParams: …` + + Parameters for sending an interrupt to pause the agent. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `class BetaManagedAgentsUserMessageEventParams: …` + + Parameters for sending a user message to the session. + + - `content: List[Content]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `class BetaManagedAgentsUserToolConfirmationEventParams: …` + + Parameters for confirming or denying a tool execution request. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`beta.sessions.resources.add(strsession_id, ResourceAddParams**kwargs) -> BetaManagedAgentsFileResource` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `session_id: str` + +- `file_id: str` + + ID of a previously uploaded file. + +- `type: Literal["file"]` + + - `"file"` + +- `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_file_resource = client.beta.sessions.resources.add( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", + file_id="file_011CNha8iCJcU1wXNR6q4V8w", + type="file", +) +print(beta_managed_agents_file_resource.id) +``` + +## List + +`beta.sessions.resources.list(strsession_id, ResourceListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSessionResource]` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `session_id: str` + +- `limit: Optional[int]` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `page: Optional[str]` + + Opaque cursor from a previous response's next_page field. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionResource` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.sessions.resources.list( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +page = page.data[0] +print(page) +``` + +## Retrieve + +`beta.sessions.resources.retrieve(strresource_id, ResourceRetrieveParams**kwargs) -> ResourceRetrieveResponse` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `session_id: str` + +- `resource_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceRetrieveResponse` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +resource = client.beta.sessions.resources.retrieve( + resource_id="sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(resource) +``` + +## Update + +`beta.sessions.resources.update(strresource_id, ResourceUpdateParams**kwargs) -> ResourceUpdateResponse` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `session_id: str` + +- `resource_id: str` + +- `authorization_token: str` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceUpdateResponse` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +resource = client.beta.sessions.resources.update( + resource_id="sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", + authorization_token="ghp_exampletoken", +) +print(resource) +``` + +## Delete + +`beta.sessions.resources.delete(strresource_id, ResourceDeleteParams**kwargs) -> BetaManagedAgentsDeleteSessionResource` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `session_id: str` + +- `resource_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource: …` + + Confirmation of resource deletion. + + - `id: str` + + - `type: Literal["session_resource_deleted"]` + + - `"session_resource_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_delete_session_resource = client.beta.sessions.resources.delete( + resource_id="sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_delete_session_resource.id) +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `class BetaManagedAgentsDeleteSessionResource: …` + + Confirmation of resource deletion. + + - `id: str` + + - `type: Literal["session_resource_deleted"]` + + - `"session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + +### Beta Managed Agents Session Resource + +- `BetaManagedAgentsSessionResource` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Resource Retrieve Response + +- `ResourceRetrieveResponse` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Resource Update Response + +- `ResourceUpdateResponse` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format diff --git a/content/en/api/python/beta/sessions/archive.md b/content/en/api/python/beta/sessions/archive.md new file mode 100644 index 000000000..41990e26e --- /dev/null +++ b/content/en/api/python/beta/sessions/archive.md @@ -0,0 +1,515 @@ +## Archive + +`beta.sessions.archive(strsession_id, SessionArchiveParams**kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_session = client.beta.sessions.archive( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_session.id) +``` diff --git a/content/en/api/python/beta/sessions/create.md b/content/en/api/python/beta/sessions/create.md new file mode 100644 index 000000000..5fcbc3468 --- /dev/null +++ b/content/en/api/python/beta/sessions/create.md @@ -0,0 +1,616 @@ +## Create + +`beta.sessions.create(SessionCreateParams**kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `agent: Agent` + + Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `str` + + - `class BetaManagedAgentsAgentParams: …` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: str` + + The `agent` ID. + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: Optional[int]` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +- `environment_id: str` + + ID of the `environment` defining the container configuration for this session. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata attached to the session. + +- `resources: Optional[Iterable[Resource]]` + + Resources (e.g. repositories, files) to mount into the session's container. + + - `class BetaManagedAgentsGitHubRepositoryResourceParams: …` + + Mount a GitHub repository into the session's container. + + - `authorization_token: str` + + GitHub authorization token used to clone the repository. + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `url: str` + + Github URL of the repository + + - `checkout: Optional[Checkout]` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/workspace/`. + + - `class BetaManagedAgentsFileResourceParams: …` + + Mount a file uploaded via the Files API into the session. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `title: Optional[str]` + + Human-readable session title. + +- `vault_ids: Optional[Sequence[str]]` + + Vault IDs for stored credentials the agent can use during the session. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_session = client.beta.sessions.create( + agent="agent_011CZkYpogX7uDKUyvBTophP", + environment_id="env_011CZkZ9X2dpNyB7HsEFoRfW", +) +print(beta_managed_agents_session.id) +``` diff --git a/content/en/api/python/beta/sessions/delete.md b/content/en/api/python/beta/sessions/delete.md new file mode 100644 index 000000000..567cb3f09 --- /dev/null +++ b/content/en/api/python/beta/sessions/delete.md @@ -0,0 +1,88 @@ +## Delete + +`beta.sessions.delete(strsession_id, SessionDeleteParams**kwargs) -> BetaManagedAgentsDeletedSession` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedSession: …` + + Confirmation that a `session` has been permanently deleted. + + - `id: str` + + - `type: Literal["session_deleted"]` + + - `"session_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_deleted_session = client.beta.sessions.delete( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_deleted_session.id) +``` diff --git a/content/en/api/python/beta/sessions/events.md b/content/en/api/python/beta/sessions/events.md new file mode 100644 index 000000000..72a1959cd --- /dev/null +++ b/content/en/api/python/beta/sessions/events.md @@ -0,0 +1,9640 @@ +# Events + +## List + +`beta.sessions.events.list(strsession_id, EventListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSessionEvent]` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `session_id: str` + +- `limit: Optional[int]` + + Query parameter for limit + +- `order: Optional[Literal["asc", "desc"]]` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"` + + - `"desc"` + +- `page: Optional[str]` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionEvent` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.sessions.events.list( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +page = page.data[0] +print(page) +``` + +## Send + +`beta.sessions.events.send(strsession_id, EventSendParams**kwargs) -> BetaManagedAgentsSendSessionEvents` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `session_id: str` + +- `events: Iterable[BetaManagedAgentsEventParams]` + + Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams: …` + + Parameters for sending a user message to the session. + + - `content: List[Content]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams: …` + + Parameters for sending an interrupt to pause the agent. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams: …` + + Parameters for confirming or denying a tool execution request. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams: …` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSendSessionEvents: …` + + Events that were successfully sent to the session. + + - `data: Optional[List[Data]]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_send_session_events = client.beta.sessions.events.send( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", + events=[{ + "content": [{ + "text": "Where is my order #1234?", + "type": "text", + }], + "type": "user.message", + }], +) +print(beta_managed_agents_send_session_events.data) +``` + +## Stream + +`beta.sessions.events.stream(strsession_id, EventStreamParams**kwargs) -> BetaManagedAgentsStreamSessionEvents` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +for event in client.beta.sessions.events.stream( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +): + print(event) +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Agent Message Event + +- `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Base64 Document Source + +- `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + +### Beta Managed Agents Base64 Image Source + +- `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + +### Beta Managed Agents Billing Error + +- `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + +### Beta Managed Agents Document Block + +- `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + +### Beta Managed Agents Event Params + +- `BetaManagedAgentsEventParams` + + Union type for event parameters that can be sent to a session. + + - `class BetaManagedAgentsUserMessageEventParams: …` + + Parameters for sending a user message to the session. + + - `content: List[Content]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams: …` + + Parameters for sending an interrupt to pause the agent. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams: …` + + Parameters for confirming or denying a tool execution request. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams: …` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + +### Beta Managed Agents File Image Source + +- `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + +### Beta Managed Agents Image Block + +- `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + +### Beta Managed Agents Retry Status Exhausted + +- `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + +### Beta Managed Agents Send Session Events + +- `class BetaManagedAgentsSendSessionEvents: …` + + Events that were successfully sent to the session. + + - `data: Optional[List[Data]]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + +### Beta Managed Agents Session Error Event + +- `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + +### Beta Managed Agents Session Event + +- `BetaManagedAgentsSessionEvent` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `class BetaManagedAgentsSpanModelUsage: …` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Stream Session Events + +- `BetaManagedAgentsStreamSessionEvents` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Beta Managed Agents Text Block + +- `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + +### Beta Managed Agents Unknown Error + +- `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + +### Beta Managed Agents URL Document Source + +- `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `class BetaManagedAgentsUserCustomToolResultEventParams: …` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `class BetaManagedAgentsUserInterruptEventParams: …` + + Parameters for sending an interrupt to pause the agent. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `class BetaManagedAgentsUserMessageEventParams: …` + + Parameters for sending a user message to the session. + + - `content: List[Content]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `class BetaManagedAgentsUserToolConfirmationEventParams: …` + + Parameters for confirming or denying a tool execution request. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. diff --git a/content/en/api/python/beta/sessions/events/list.md b/content/en/api/python/beta/sessions/events/list.md new file mode 100644 index 000000000..05fe09c75 --- /dev/null +++ b/content/en/api/python/beta/sessions/events/list.md @@ -0,0 +1,1463 @@ +## List + +`beta.sessions.events.list(strsession_id, EventListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSessionEvent]` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `session_id: str` + +- `limit: Optional[int]` + + Query parameter for limit + +- `order: Optional[Literal["asc", "desc"]]` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"` + + - `"desc"` + +- `page: Optional[str]` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionEvent` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.sessions.events.list( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +page = page.data[0] +print(page) +``` diff --git a/content/en/api/python/beta/sessions/events/send.md b/content/en/api/python/beta/sessions/events/send.md new file mode 100644 index 000000000..4a13a8551 --- /dev/null +++ b/content/en/api/python/beta/sessions/events/send.md @@ -0,0 +1,825 @@ +## Send + +`beta.sessions.events.send(strsession_id, EventSendParams**kwargs) -> BetaManagedAgentsSendSessionEvents` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `session_id: str` + +- `events: Iterable[BetaManagedAgentsEventParams]` + + Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams: …` + + Parameters for sending a user message to the session. + + - `content: List[Content]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams: …` + + Parameters for sending an interrupt to pause the agent. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams: …` + + Parameters for confirming or denying a tool execution request. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams: …` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSendSessionEvents: …` + + Events that were successfully sent to the session. + + - `data: Optional[List[Data]]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_send_session_events = client.beta.sessions.events.send( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", + events=[{ + "content": [{ + "text": "Where is my order #1234?", + "type": "text", + }], + "type": "user.message", + }], +) +print(beta_managed_agents_send_session_events.data) +``` diff --git a/content/en/api/python/beta/sessions/events/stream.md b/content/en/api/python/beta/sessions/events/stream.md new file mode 100644 index 000000000..faca8ffe0 --- /dev/null +++ b/content/en/api/python/beta/sessions/events/stream.md @@ -0,0 +1,1446 @@ +## Stream + +`beta.sessions.events.stream(strsession_id, EventStreamParams**kwargs) -> BetaManagedAgentsStreamSessionEvents` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent: …` + + A user message event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[Content]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `type: Literal["user.message"]` + + - `"user.message"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent: …` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: str` + + Unique identifier for this event. + + - `type: Literal["user.interrupt"]` + + - `"user.interrupt"` + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent: …` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: str` + + Unique identifier for this event. + + - `result: Literal["allow", "deny"]` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: str` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.tool_confirmation"]` + + - `"user.tool_confirmation"` + + - `deny_message: Optional[str]` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent: …` + + Event sent by the client providing the result of a custom tool execution. + + - `id: str` + + Unique identifier for this event. + + - `custom_tool_use_id: str` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: Literal["user.custom_tool_result"]` + + - `"user.custom_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `processed_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent: …` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the custom tool being called. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.custom_tool_use"]` + + - `"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent: …` + + An agent response event in the session conversation. + + - `id: str` + + Unique identifier for this event. + + - `content: List[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.message"]` + + - `"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent: …` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thinking"]` + + - `"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent: …` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `mcp_server_name: str` + + Name of the MCP server providing the tool. + + - `name: str` + + Name of the MCP tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_use"]` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentMCPToolResultEvent: …` + + Event representing the result of an MCP tool execution. + + - `id: str` + + Unique identifier for this event. + + - `mcp_tool_use_id: str` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.mcp_tool_result"]` + + - `"agent.mcp_tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent: …` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: str` + + Unique identifier for this event. + + - `input: Dict[str, object]` + + Input parameters for the tool call. + + - `name: str` + + Name of the agent tool being used. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.tool_use"]` + + - `"agent.tool_use"` + + - `evaluated_permission: Optional[Literal["allow", "ask", "deny"]]` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `class BetaManagedAgentsAgentToolResultEvent: …` + + Event representing the result of an agent tool execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `tool_use_id: str` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: Literal["agent.tool_result"]` + + - `"agent.tool_result"` + + - `content: Optional[List[Content]]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock: …` + + Regular text content. + + - `text: str` + + The text content. + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsImageBlock: …` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: Source` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource: …` + + Base64-encoded image data. + + - `data: str` + + Base64-encoded image data. + + - `media_type: str` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsURLImageSource: …` + + Image referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource: …` + + Image referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["image"]` + + - `"image"` + + - `class BetaManagedAgentsDocumentBlock: …` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: Source` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource: …` + + Base64-encoded document data. + + - `data: str` + + Base64-encoded document data. + + - `media_type: str` + + MIME type of the document (e.g., "application/pdf"). + + - `type: Literal["base64"]` + + - `"base64"` + + - `class BetaManagedAgentsPlainTextDocumentSource: …` + + Plain text document content. + + - `data: str` + + The plain text content. + + - `media_type: Literal["text/plain"]` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: Literal["text"]` + + - `"text"` + + - `class BetaManagedAgentsURLDocumentSource: …` + + Document referenced by URL. + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource: …` + + Document referenced by file ID. + + - `file_id: str` + + ID of a previously uploaded file. + + - `type: Literal["file"]` + + - `"file"` + + - `type: Literal["document"]` + + - `"document"` + + - `context: Optional[str]` + + Additional context about the document for the model. + + - `title: Optional[str]` + + The title of the document. + + - `is_error: Optional[bool]` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent: …` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["agent.thread_context_compacted"]` + + - `"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent: …` + + An error event indicating a problem occurred during session execution. + + - `id: str` + + Unique identifier for this event. + + - `error: Error` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError: …` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["unknown_error"]` + + - `"unknown_error"` + + - `class BetaManagedAgentsModelOverloadedError: …` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_overloaded_error"]` + + - `"model_overloaded_error"` + + - `class BetaManagedAgentsModelRateLimitedError: …` + + The model request was rate-limited. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_rate_limited_error"]` + + - `"model_rate_limited_error"` + + - `class BetaManagedAgentsModelRequestFailedError: …` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["model_request_failed_error"]` + + - `"model_request_failed_error"` + + - `class BetaManagedAgentsMCPConnectionFailedError: …` + + Failed to connect to an MCP server. + + - `mcp_server_name: str` + + Name of the MCP server that failed to connect. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_connection_failed_error"]` + + - `"mcp_connection_failed_error"` + + - `class BetaManagedAgentsMCPAuthenticationFailedError: …` + + Authentication to an MCP server failed. + + - `mcp_server_name: str` + + Name of the MCP server that failed authentication. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["mcp_authentication_failed_error"]` + + - `"mcp_authentication_failed_error"` + + - `class BetaManagedAgentsBillingError: …` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: str` + + Human-readable error description. + + - `retry_status: RetryStatus` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying: …` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: Literal["retrying"]` + + - `"retrying"` + + - `class BetaManagedAgentsRetryStatusExhausted: …` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: Literal["exhausted"]` + + - `"exhausted"` + + - `class BetaManagedAgentsRetryStatusTerminal: …` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: Literal["terminal"]` + + - `"terminal"` + + - `type: Literal["billing_error"]` + + - `"billing_error"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.error"]` + + - `"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent: …` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_rescheduled"]` + + - `"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent: …` + + Indicates the session is actively running and the agent is working. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_running"]` + + - `"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent: …` + + Indicates the agent has paused and is awaiting user input. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `stop_reason: StopReason` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn: …` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: Literal["end_turn"]` + + - `"end_turn"` + + - `class BetaManagedAgentsSessionRequiresAction: …` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: List[str]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: Literal["requires_action"]` + + - `"requires_action"` + + - `class BetaManagedAgentsSessionRetriesExhausted: …` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: Literal["retries_exhausted"]` + + - `"retries_exhausted"` + + - `type: Literal["session.status_idle"]` + + - `"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent: …` + + Indicates the session has terminated, either due to an error or completion. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.status_terminated"]` + + - `"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent: …` + + Emitted when a model request is initiated by the agent. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_start"]` + + - `"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent: …` + + Emitted when a model request completes. + + - `id: str` + + Unique identifier for this event. + + - `is_error: Optional[bool]` + + Whether the model request resulted in an error. + + - `model_request_start_id: str` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: int` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: int` + + Tokens read from prompt cache in this request. + + - `input_tokens: int` + + Input tokens consumed by this request. + + - `output_tokens: int` + + Output tokens generated by this request. + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["span.model_request_end"]` + + - `"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent: …` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: str` + + Unique identifier for this event. + + - `processed_at: datetime` + + A timestamp in RFC 3339 format + + - `type: Literal["session.deleted"]` + + - `"session.deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +for event in client.beta.sessions.events.stream( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +): + print(event) +``` diff --git a/content/en/api/python/beta/sessions/list.md b/content/en/api/python/beta/sessions/list.md new file mode 100644 index 000000000..f2a2a22d5 --- /dev/null +++ b/content/en/api/python/beta/sessions/list.md @@ -0,0 +1,556 @@ +## List + +`beta.sessions.list(SessionListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSession]` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `agent_id: Optional[str]` + + Filter sessions created with this agent ID. + +- `agent_version: Optional[int]` + + Filter by agent version. Only applies when agent_id is also set. + +- `created_at_gt: Optional[Union[str, datetime]]` + + Return sessions created after this time (exclusive). + +- `created_at_gte: Optional[Union[str, datetime]]` + + Return sessions created at or after this time (inclusive). + +- `created_at_lt: Optional[Union[str, datetime]]` + + Return sessions created before this time (exclusive). + +- `created_at_lte: Optional[Union[str, datetime]]` + + Return sessions created at or before this time (inclusive). + +- `include_archived: Optional[bool]` + + When true, includes archived sessions. Default: false (exclude archived). + +- `limit: Optional[int]` + + Maximum number of results to return. + +- `order: Optional[Literal["asc", "desc"]]` + + Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `"asc"` + + - `"desc"` + +- `page: Optional[str]` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.sessions.list() +page = page.data[0] +print(page.id) +``` diff --git a/content/en/api/python/beta/sessions/resources.md b/content/en/api/python/beta/sessions/resources.md new file mode 100644 index 000000000..a25653486 --- /dev/null +++ b/content/en/api/python/beta/sessions/resources.md @@ -0,0 +1,941 @@ +# Resources + +## Add + +`beta.sessions.resources.add(strsession_id, ResourceAddParams**kwargs) -> BetaManagedAgentsFileResource` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `session_id: str` + +- `file_id: str` + + ID of a previously uploaded file. + +- `type: Literal["file"]` + + - `"file"` + +- `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_file_resource = client.beta.sessions.resources.add( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", + file_id="file_011CNha8iCJcU1wXNR6q4V8w", + type="file", +) +print(beta_managed_agents_file_resource.id) +``` + +## List + +`beta.sessions.resources.list(strsession_id, ResourceListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSessionResource]` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `session_id: str` + +- `limit: Optional[int]` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `page: Optional[str]` + + Opaque cursor from a previous response's next_page field. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionResource` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.sessions.resources.list( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +page = page.data[0] +print(page) +``` + +## Retrieve + +`beta.sessions.resources.retrieve(strresource_id, ResourceRetrieveParams**kwargs) -> ResourceRetrieveResponse` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `session_id: str` + +- `resource_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceRetrieveResponse` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +resource = client.beta.sessions.resources.retrieve( + resource_id="sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(resource) +``` + +## Update + +`beta.sessions.resources.update(strresource_id, ResourceUpdateParams**kwargs) -> ResourceUpdateResponse` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `session_id: str` + +- `resource_id: str` + +- `authorization_token: str` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceUpdateResponse` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +resource = client.beta.sessions.resources.update( + resource_id="sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", + authorization_token="ghp_exampletoken", +) +print(resource) +``` + +## Delete + +`beta.sessions.resources.delete(strresource_id, ResourceDeleteParams**kwargs) -> BetaManagedAgentsDeleteSessionResource` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `session_id: str` + +- `resource_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource: …` + + Confirmation of resource deletion. + + - `id: str` + + - `type: Literal["session_resource_deleted"]` + + - `"session_resource_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_delete_session_resource = client.beta.sessions.resources.delete( + resource_id="sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_delete_session_resource.id) +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `class BetaManagedAgentsDeleteSessionResource: …` + + Confirmation of resource deletion. + + - `id: str` + + - `type: Literal["session_resource_deleted"]` + + - `"session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + +### Beta Managed Agents Session Resource + +- `BetaManagedAgentsSessionResource` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Resource Retrieve Response + +- `ResourceRetrieveResponse` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Resource Update Response + +- `ResourceUpdateResponse` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format diff --git a/content/en/api/python/beta/sessions/resources/add.md b/content/en/api/python/beta/sessions/resources/add.md new file mode 100644 index 000000000..34ea44791 --- /dev/null +++ b/content/en/api/python/beta/sessions/resources/add.md @@ -0,0 +1,112 @@ +## Add + +`beta.sessions.resources.add(strsession_id, ResourceAddParams**kwargs) -> BetaManagedAgentsFileResource` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `session_id: str` + +- `file_id: str` + + ID of a previously uploaded file. + +- `type: Literal["file"]` + + - `"file"` + +- `mount_path: Optional[str]` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_file_resource = client.beta.sessions.resources.add( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", + file_id="file_011CNha8iCJcU1wXNR6q4V8w", + type="file", +) +print(beta_managed_agents_file_resource.id) +``` diff --git a/content/en/api/python/beta/sessions/resources/delete.md b/content/en/api/python/beta/sessions/resources/delete.md new file mode 100644 index 000000000..1434d1fbb --- /dev/null +++ b/content/en/api/python/beta/sessions/resources/delete.md @@ -0,0 +1,91 @@ +## Delete + +`beta.sessions.resources.delete(strresource_id, ResourceDeleteParams**kwargs) -> BetaManagedAgentsDeleteSessionResource` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `session_id: str` + +- `resource_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource: …` + + Confirmation of resource deletion. + + - `id: str` + + - `type: Literal["session_resource_deleted"]` + + - `"session_resource_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_delete_session_resource = client.beta.sessions.resources.delete( + resource_id="sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_delete_session_resource.id) +``` diff --git a/content/en/api/python/beta/sessions/resources/list.md b/content/en/api/python/beta/sessions/resources/list.md new file mode 100644 index 000000000..17d608b64 --- /dev/null +++ b/content/en/api/python/beta/sessions/resources/list.md @@ -0,0 +1,151 @@ +## List + +`beta.sessions.resources.list(strsession_id, ResourceListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSessionResource]` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `session_id: str` + +- `limit: Optional[int]` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `page: Optional[str]` + + Opaque cursor from a previous response's next_page field. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionResource` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.sessions.resources.list( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +page = page.data[0] +print(page) +``` diff --git a/content/en/api/python/beta/sessions/resources/retrieve.md b/content/en/api/python/beta/sessions/resources/retrieve.md new file mode 100644 index 000000000..2b5c07224 --- /dev/null +++ b/content/en/api/python/beta/sessions/resources/retrieve.md @@ -0,0 +1,147 @@ +## Retrieve + +`beta.sessions.resources.retrieve(strresource_id, ResourceRetrieveParams**kwargs) -> ResourceRetrieveResponse` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `session_id: str` + +- `resource_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceRetrieveResponse` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +resource = client.beta.sessions.resources.retrieve( + resource_id="sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(resource) +``` diff --git a/content/en/api/python/beta/sessions/resources/update.md b/content/en/api/python/beta/sessions/resources/update.md new file mode 100644 index 000000000..d129f58f0 --- /dev/null +++ b/content/en/api/python/beta/sessions/resources/update.md @@ -0,0 +1,152 @@ +## Update + +`beta.sessions.resources.update(strresource_id, ResourceUpdateParams**kwargs) -> ResourceUpdateResponse` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `session_id: str` + +- `resource_id: str` + +- `authorization_token: str` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceUpdateResponse` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +resource = client.beta.sessions.resources.update( + resource_id="sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", + authorization_token="ghp_exampletoken", +) +print(resource) +``` diff --git a/content/en/api/python/beta/sessions/retrieve.md b/content/en/api/python/beta/sessions/retrieve.md new file mode 100644 index 000000000..b97f0d352 --- /dev/null +++ b/content/en/api/python/beta/sessions/retrieve.md @@ -0,0 +1,515 @@ +## Retrieve + +`beta.sessions.retrieve(strsession_id, SessionRetrieveParams**kwargs) -> BetaManagedAgentsSession` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `session_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_session = client.beta.sessions.retrieve( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_session.id) +``` diff --git a/content/en/api/python/beta/sessions/update.md b/content/en/api/python/beta/sessions/update.md new file mode 100644 index 000000000..2b2d5b5cf --- /dev/null +++ b/content/en/api/python/beta/sessions/update.md @@ -0,0 +1,527 @@ +## Update + +`beta.sessions.update(strsession_id, SessionUpdateParams**kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `session_id: str` + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + +- `title: Optional[str]` + + Human-readable session title. + +- `vault_ids: Optional[Sequence[str]]` + + Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession: …` + + A Managed Agents `session`. + + - `id: str` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: str` + + - `description: Optional[str]` + + - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: str` + + - `type: Literal["url"]` + + - `"url"` + + - `url: str` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 5 more]` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-sonnet-4-6` - Best combination of speed and intelligence + - `claude-haiku-4-5` - Fastest model with near-frontier intelligence + - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence + - `claude-opus-4-5` - Premium model combining maximum intelligence with practical performance + - `claude-opus-4-5-20251101` - Premium model combining maximum intelligence with practical performance + - `claude-sonnet-4-5` - High-performance model for agents and coding + - `claude-sonnet-4-5-20250929` - High-performance model for agents and coding + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `str` + + - `speed: Optional[Literal["standard", "fast"]]` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: str` + + - `skills: List[Skill]` + + - `class BetaManagedAgentsAnthropicSkill: …` + + A resolved Anthropic-managed skill. + + - `skill_id: str` + + - `type: Literal["anthropic"]` + + - `"anthropic"` + + - `version: str` + + - `class BetaManagedAgentsCustomSkill: …` + + A resolved user-created custom skill. + + - `skill_id: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `version: str` + + - `system: Optional[str]` + + - `tools: List[Tool]` + + - `class BetaManagedAgentsAgentToolset20260401: …` + + - `configs: List[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: Literal["bash", "edit", "read", 5 more]` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `type: Literal["agent_toolset_20260401"]` + + - `"agent_toolset_20260401"` + + - `class BetaManagedAgentsMCPToolset: …` + + - `configs: List[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: str` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: PermissionPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy: …` + + Tool calls are automatically approved without user confirmation. + + - `type: Literal["always_allow"]` + + - `"always_allow"` + + - `class BetaManagedAgentsAlwaysAskPolicy: …` + + Tool calls require user confirmation before execution. + + - `type: Literal["always_ask"]` + + - `"always_ask"` + + - `mcp_server_name: str` + + - `type: Literal["mcp_toolset"]` + + - `"mcp_toolset"` + + - `class BetaManagedAgentsCustomTool: …` + + A custom tool as returned in API responses. + + - `description: str` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Optional[Dict[str, object]]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Optional[List[str]]` + + List of required property names. + + - `type: Optional[Literal["object"]]` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: str` + + - `type: Literal["custom"]` + + - `"custom"` + + - `type: Literal["agent"]` + + - `"agent"` + + - `version: int` + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `environment_id: str` + + - `metadata: Dict[str, str]` + + - `resources: List[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `mount_path: str` + + - `type: Literal["github_repository"]` + + - `"github_repository"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `url: str` + + - `checkout: Optional[Checkout]` + + - `class BetaManagedAgentsBranchCheckout: …` + + - `name: str` + + Branch name to check out. + + - `type: Literal["branch"]` + + - `"branch"` + + - `class BetaManagedAgentsCommitCheckout: …` + + - `sha: str` + + Full commit SHA to check out. + + - `type: Literal["commit"]` + + - `"commit"` + + - `class BetaManagedAgentsFileResource: …` + + - `id: str` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `file_id: str` + + - `mount_path: str` + + - `type: Literal["file"]` + + - `"file"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Optional[float]` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Optional[float]` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: Literal["rescheduling", "running", "idle", "terminated"]` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: Optional[str]` + + - `type: Literal["session"]` + + - `"session"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: Optional[BetaManagedAgentsCacheCreationUsage]` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Optional[int]` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Optional[int]` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Optional[int]` + + Total tokens read from prompt cache. + + - `input_tokens: Optional[int]` + + Total input tokens consumed across all turns. + + - `output_tokens: Optional[int]` + + Total output tokens generated across all turns. + + - `vault_ids: List[str]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_session = client.beta.sessions.update( + session_id="sesn_011CZkZAtmR3yMPDzynEDxu7", +) +print(beta_managed_agents_session.id) +``` diff --git a/content/en/api/python/beta/skills.md b/content/en/api/python/beta/skills.md index b5a1f3d58..d2118840d 100644 --- a/content/en/api/python/beta/skills.md +++ b/content/en/api/python/beta/skills.md @@ -28,7 +28,7 @@ Create Skill - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -72,8 +72,6 @@ Create Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class SkillCreateResponse: …` @@ -169,7 +167,7 @@ List Skills - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -213,8 +211,6 @@ List Skills - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class SkillListResponse: …` @@ -296,7 +292,7 @@ Get Skill - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -340,8 +336,6 @@ Get Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class SkillRetrieveResponse: …` @@ -424,7 +418,7 @@ Delete Skill - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -468,8 +462,6 @@ Delete Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class SkillDeleteResponse: …` @@ -684,7 +676,7 @@ Create Skill Version - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -728,8 +720,6 @@ Create Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionCreateResponse: …` @@ -825,7 +815,7 @@ List Skill Versions - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -869,8 +859,6 @@ List Skill Versions - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionListResponse: …` @@ -963,7 +951,7 @@ Get Skill Version - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -1007,8 +995,6 @@ Get Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionRetrieveResponse: …` @@ -1101,7 +1087,7 @@ Delete Skill Version - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -1145,8 +1131,6 @@ Delete Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionDeleteResponse: …` diff --git a/content/en/api/python/beta/skills/create.md b/content/en/api/python/beta/skills/create.md index f3506b9b7..d05f99330 100644 --- a/content/en/api/python/beta/skills/create.md +++ b/content/en/api/python/beta/skills/create.md @@ -26,7 +26,7 @@ Create Skill - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -70,8 +70,6 @@ Create Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class SkillCreateResponse: …` diff --git a/content/en/api/python/beta/skills/delete.md b/content/en/api/python/beta/skills/delete.md index 5c42bc768..a5c12be07 100644 --- a/content/en/api/python/beta/skills/delete.md +++ b/content/en/api/python/beta/skills/delete.md @@ -20,7 +20,7 @@ Delete Skill - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Delete Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class SkillDeleteResponse: …` diff --git a/content/en/api/python/beta/skills/list.md b/content/en/api/python/beta/skills/list.md index 531531388..1d02bf843 100644 --- a/content/en/api/python/beta/skills/list.md +++ b/content/en/api/python/beta/skills/list.md @@ -35,7 +35,7 @@ List Skills - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -79,8 +79,6 @@ List Skills - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class SkillListResponse: …` diff --git a/content/en/api/python/beta/skills/retrieve.md b/content/en/api/python/beta/skills/retrieve.md index b2d9373ab..b57abef1d 100644 --- a/content/en/api/python/beta/skills/retrieve.md +++ b/content/en/api/python/beta/skills/retrieve.md @@ -20,7 +20,7 @@ Get Skill - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Get Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class SkillRetrieveResponse: …` diff --git a/content/en/api/python/beta/skills/versions.md b/content/en/api/python/beta/skills/versions.md index adcbdf70f..95da06a81 100644 --- a/content/en/api/python/beta/skills/versions.md +++ b/content/en/api/python/beta/skills/versions.md @@ -28,7 +28,7 @@ Create Skill Version - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -72,8 +72,6 @@ Create Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionCreateResponse: …` @@ -169,7 +167,7 @@ List Skill Versions - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -213,8 +211,6 @@ List Skill Versions - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionListResponse: …` @@ -307,7 +303,7 @@ Get Skill Version - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -351,8 +347,6 @@ Get Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionRetrieveResponse: …` @@ -445,7 +439,7 @@ Delete Skill Version - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -489,8 +483,6 @@ Delete Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionDeleteResponse: …` diff --git a/content/en/api/python/beta/skills/versions/create.md b/content/en/api/python/beta/skills/versions/create.md index a12d81eb5..56b589294 100644 --- a/content/en/api/python/beta/skills/versions/create.md +++ b/content/en/api/python/beta/skills/versions/create.md @@ -26,7 +26,7 @@ Create Skill Version - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -70,8 +70,6 @@ Create Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionCreateResponse: …` diff --git a/content/en/api/python/beta/skills/versions/delete.md b/content/en/api/python/beta/skills/versions/delete.md index dded09232..cc8726c2e 100644 --- a/content/en/api/python/beta/skills/versions/delete.md +++ b/content/en/api/python/beta/skills/versions/delete.md @@ -26,7 +26,7 @@ Delete Skill Version - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -70,8 +70,6 @@ Delete Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionDeleteResponse: …` diff --git a/content/en/api/python/beta/skills/versions/list.md b/content/en/api/python/beta/skills/versions/list.md index f05b870fc..64d55d88a 100644 --- a/content/en/api/python/beta/skills/versions/list.md +++ b/content/en/api/python/beta/skills/versions/list.md @@ -30,7 +30,7 @@ List Skill Versions - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ List Skill Versions - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionListResponse: …` diff --git a/content/en/api/python/beta/skills/versions/retrieve.md b/content/en/api/python/beta/skills/versions/retrieve.md index 49b50c4a1..f887da8e2 100644 --- a/content/en/api/python/beta/skills/versions/retrieve.md +++ b/content/en/api/python/beta/skills/versions/retrieve.md @@ -26,7 +26,7 @@ Get Skill Version - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -70,8 +70,6 @@ Get Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class VersionRetrieveResponse: …` diff --git a/content/en/api/python/beta/vaults.md b/content/en/api/python/beta/vaults.md new file mode 100644 index 000000000..86e29c783 --- /dev/null +++ b/content/en/api/python/beta/vaults.md @@ -0,0 +1,2642 @@ +# Vaults + +## Create + +`beta.vaults.create(VaultCreateParams**kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `display_name: str` + + Human-readable name for the vault. 1-255 characters. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata to attach to the vault. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_vault = client.beta.vaults.create( + display_name="Example vault", +) +print(beta_managed_agents_vault.id) +``` + +## List + +`beta.vaults.list(VaultListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsVault]` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `include_archived: Optional[bool]` + + Whether to include archived vaults in the results. + +- `limit: Optional[int]` + + Maximum number of vaults to return per page. Defaults to 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination token from a previous `list_vaults` response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.vaults.list() +page = page.data[0] +print(page.id) +``` + +## Retrieve + +`beta.vaults.retrieve(strvault_id, VaultRetrieveParams**kwargs) -> BetaManagedAgentsVault` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `vault_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_vault = client.beta.vaults.retrieve( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_vault.id) +``` + +## Update + +`beta.vaults.update(strvault_id, VaultUpdateParams**kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `vault_id: str` + +- `display_name: Optional[str]` + + Updated human-readable name for the vault. 1-255 characters. + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_vault = client.beta.vaults.update( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_vault.id) +``` + +## Delete + +`beta.vaults.delete(strvault_id, VaultDeleteParams**kwargs) -> BetaManagedAgentsDeletedVault` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `vault_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedVault: …` + + Confirmation of a deleted vault. + + - `id: str` + + Unique identifier of the deleted vault. + + - `type: Literal["vault_deleted"]` + + - `"vault_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_deleted_vault = client.beta.vaults.delete( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_deleted_vault.id) +``` + +## Archive + +`beta.vaults.archive(strvault_id, VaultArchiveParams**kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `vault_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_vault = client.beta.vaults.archive( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_vault.id) +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `class BetaManagedAgentsDeletedVault: …` + + Confirmation of a deleted vault. + + - `id: str` + + Unique identifier of the deleted vault. + + - `type: Literal["vault_deleted"]` + + - `"vault_deleted"` + +### Beta Managed Agents Vault + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`beta.vaults.credentials.create(strvault_id, CredentialCreateParams**kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vault_id: str` + +- `auth: Auth` + + Authentication details for creating a credential. + + - `class BetaManagedAgentsMCPOAuthCreateParams: …` + + Parameters for creating an MCP OAuth credential. + + - `access_token: str` + + OAuth access token. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshParams]` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: str` + + OAuth client ID. + + - `refresh_token: str` + + OAuth refresh token. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams: …` + + Parameters for creating a static bearer token credential. + + - `token: str` + + Static bearer token value. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + +- `display_name: Optional[str]` + + Human-readable name for the credential. Up to 255 characters. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata to attach to the credential. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.create( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", + auth={ + "token": "bearer_exampletoken", + "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", + "type": "static_bearer", + }, +) +print(beta_managed_agents_credential.id) +``` + +## List + +`beta.vaults.credentials.list(strvault_id, CredentialListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsCredential]` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vault_id: str` + +- `include_archived: Optional[bool]` + + Whether to include archived credentials in the results. + +- `limit: Optional[int]` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination token from a previous `list_credentials` response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.vaults.credentials.list( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +page = page.data[0] +print(page.id) +``` + +## Retrieve + +`beta.vaults.credentials.retrieve(strcredential_id, CredentialRetrieveParams**kwargs) -> BetaManagedAgentsCredential` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.retrieve( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_credential.id) +``` + +## Update + +`beta.vaults.credentials.update(strcredential_id, CredentialUpdateParams**kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `auth: Optional[Auth]` + + Updated authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthUpdateParams: …` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `access_token: Optional[str]` + + Updated OAuth access token. + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshUpdateParams]` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: Optional[str]` + + Updated OAuth refresh token. + + - `scope: Optional[str]` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: Optional[TokenEndpointAuth]` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams: …` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `token: Optional[str]` + + Updated static bearer token value. + +- `display_name: Optional[str]` + + Updated human-readable name for the credential. 1-255 characters. + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.update( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_credential.id) +``` + +## Delete + +`beta.vaults.credentials.delete(strcredential_id, CredentialDeleteParams**kwargs) -> BetaManagedAgentsDeletedCredential` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedCredential: …` + + Confirmation of a deleted credential. + + - `id: str` + + Unique identifier of the deleted credential. + + - `type: Literal["vault_credential_deleted"]` + + - `"vault_credential_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_deleted_credential = client.beta.vaults.credentials.delete( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_deleted_credential.id) +``` + +## Archive + +`beta.vaults.credentials.archive(strcredential_id, CredentialArchiveParams**kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.archive( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_credential.id) +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `class BetaManagedAgentsDeletedCredential: …` + + Confirmation of a deleted credential. + + - `id: str` + + Unique identifier of the deleted credential. + + - `type: Literal["vault_credential_deleted"]` + + - `"vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `class BetaManagedAgentsMCPOAuthCreateParams: …` + + Parameters for creating an MCP OAuth credential. + + - `access_token: str` + + OAuth access token. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshParams]` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: str` + + OAuth client ID. + + - `refresh_token: str` + + OAuth refresh token. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `class BetaManagedAgentsMCPOAuthRefreshParams: …` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: str` + + OAuth client ID. + + - `refresh_token: str` + + OAuth refresh token. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `class BetaManagedAgentsMCPOAuthRefreshResponse: …` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `class BetaManagedAgentsMCPOAuthRefreshUpdateParams: …` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: Optional[str]` + + Updated OAuth refresh token. + + - `scope: Optional[str]` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: Optional[TokenEndpointAuth]` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `class BetaManagedAgentsMCPOAuthUpdateParams: …` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `access_token: Optional[str]` + + Updated OAuth access token. + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshUpdateParams]` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: Optional[str]` + + Updated OAuth refresh token. + + - `scope: Optional[str]` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: Optional[TokenEndpointAuth]` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `class BetaManagedAgentsStaticBearerCreateParams: …` + + Parameters for creating a static bearer token credential. + + - `token: str` + + Static bearer token value. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `class BetaManagedAgentsStaticBearerUpdateParams: …` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `token: Optional[str]` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. diff --git a/content/en/api/python/beta/vaults/archive.md b/content/en/api/python/beta/vaults/archive.md new file mode 100644 index 000000000..53484d96d --- /dev/null +++ b/content/en/api/python/beta/vaults/archive.md @@ -0,0 +1,110 @@ +## Archive + +`beta.vaults.archive(strvault_id, VaultArchiveParams**kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `vault_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_vault = client.beta.vaults.archive( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_vault.id) +``` diff --git a/content/en/api/python/beta/vaults/create.md b/content/en/api/python/beta/vaults/create.md new file mode 100644 index 000000000..427f3236f --- /dev/null +++ b/content/en/api/python/beta/vaults/create.md @@ -0,0 +1,116 @@ +## Create + +`beta.vaults.create(VaultCreateParams**kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `display_name: str` + + Human-readable name for the vault. 1-255 characters. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata to attach to the vault. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_vault = client.beta.vaults.create( + display_name="Example vault", +) +print(beta_managed_agents_vault.id) +``` diff --git a/content/en/api/python/beta/vaults/credentials.md b/content/en/api/python/beta/vaults/credentials.md new file mode 100644 index 000000000..c5cd348c4 --- /dev/null +++ b/content/en/api/python/beta/vaults/credentials.md @@ -0,0 +1,1921 @@ +# Credentials + +## Create + +`beta.vaults.credentials.create(strvault_id, CredentialCreateParams**kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vault_id: str` + +- `auth: Auth` + + Authentication details for creating a credential. + + - `class BetaManagedAgentsMCPOAuthCreateParams: …` + + Parameters for creating an MCP OAuth credential. + + - `access_token: str` + + OAuth access token. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshParams]` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: str` + + OAuth client ID. + + - `refresh_token: str` + + OAuth refresh token. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams: …` + + Parameters for creating a static bearer token credential. + + - `token: str` + + Static bearer token value. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + +- `display_name: Optional[str]` + + Human-readable name for the credential. Up to 255 characters. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata to attach to the credential. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.create( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", + auth={ + "token": "bearer_exampletoken", + "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", + "type": "static_bearer", + }, +) +print(beta_managed_agents_credential.id) +``` + +## List + +`beta.vaults.credentials.list(strvault_id, CredentialListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsCredential]` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vault_id: str` + +- `include_archived: Optional[bool]` + + Whether to include archived credentials in the results. + +- `limit: Optional[int]` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination token from a previous `list_credentials` response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.vaults.credentials.list( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +page = page.data[0] +print(page.id) +``` + +## Retrieve + +`beta.vaults.credentials.retrieve(strcredential_id, CredentialRetrieveParams**kwargs) -> BetaManagedAgentsCredential` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.retrieve( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_credential.id) +``` + +## Update + +`beta.vaults.credentials.update(strcredential_id, CredentialUpdateParams**kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `auth: Optional[Auth]` + + Updated authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthUpdateParams: …` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `access_token: Optional[str]` + + Updated OAuth access token. + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshUpdateParams]` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: Optional[str]` + + Updated OAuth refresh token. + + - `scope: Optional[str]` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: Optional[TokenEndpointAuth]` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams: …` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `token: Optional[str]` + + Updated static bearer token value. + +- `display_name: Optional[str]` + + Updated human-readable name for the credential. 1-255 characters. + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.update( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_credential.id) +``` + +## Delete + +`beta.vaults.credentials.delete(strcredential_id, CredentialDeleteParams**kwargs) -> BetaManagedAgentsDeletedCredential` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedCredential: …` + + Confirmation of a deleted credential. + + - `id: str` + + Unique identifier of the deleted credential. + + - `type: Literal["vault_credential_deleted"]` + + - `"vault_credential_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_deleted_credential = client.beta.vaults.credentials.delete( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_deleted_credential.id) +``` + +## Archive + +`beta.vaults.credentials.archive(strcredential_id, CredentialArchiveParams**kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.archive( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_credential.id) +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `class BetaManagedAgentsDeletedCredential: …` + + Confirmation of a deleted credential. + + - `id: str` + + Unique identifier of the deleted credential. + + - `type: Literal["vault_credential_deleted"]` + + - `"vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `class BetaManagedAgentsMCPOAuthCreateParams: …` + + Parameters for creating an MCP OAuth credential. + + - `access_token: str` + + OAuth access token. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshParams]` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: str` + + OAuth client ID. + + - `refresh_token: str` + + OAuth refresh token. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `class BetaManagedAgentsMCPOAuthRefreshParams: …` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: str` + + OAuth client ID. + + - `refresh_token: str` + + OAuth refresh token. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `class BetaManagedAgentsMCPOAuthRefreshResponse: …` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `class BetaManagedAgentsMCPOAuthRefreshUpdateParams: …` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: Optional[str]` + + Updated OAuth refresh token. + + - `scope: Optional[str]` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: Optional[TokenEndpointAuth]` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `class BetaManagedAgentsMCPOAuthUpdateParams: …` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `access_token: Optional[str]` + + Updated OAuth access token. + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshUpdateParams]` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: Optional[str]` + + Updated OAuth refresh token. + + - `scope: Optional[str]` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: Optional[TokenEndpointAuth]` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `class BetaManagedAgentsStaticBearerCreateParams: …` + + Parameters for creating a static bearer token credential. + + - `token: str` + + Static bearer token value. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `class BetaManagedAgentsStaticBearerUpdateParams: …` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `token: Optional[str]` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. diff --git a/content/en/api/python/beta/vaults/credentials/archive.md b/content/en/api/python/beta/vaults/credentials/archive.md new file mode 100644 index 000000000..b59ad6fd7 --- /dev/null +++ b/content/en/api/python/beta/vaults/credentials/archive.md @@ -0,0 +1,197 @@ +## Archive + +`beta.vaults.credentials.archive(strcredential_id, CredentialArchiveParams**kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.archive( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_credential.id) +``` diff --git a/content/en/api/python/beta/vaults/credentials/create.md b/content/en/api/python/beta/vaults/credentials/create.md new file mode 100644 index 000000000..92c0b50d7 --- /dev/null +++ b/content/en/api/python/beta/vaults/credentials/create.md @@ -0,0 +1,307 @@ +## Create + +`beta.vaults.credentials.create(strvault_id, CredentialCreateParams**kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vault_id: str` + +- `auth: Auth` + + Authentication details for creating a credential. + + - `class BetaManagedAgentsMCPOAuthCreateParams: …` + + Parameters for creating an MCP OAuth credential. + + - `access_token: str` + + OAuth access token. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshParams]` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: str` + + OAuth client ID. + + - `refresh_token: str` + + OAuth refresh token. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam: …` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: str` + + OAuth client secret. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams: …` + + Parameters for creating a static bearer token credential. + + - `token: str` + + Static bearer token value. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + +- `display_name: Optional[str]` + + Human-readable name for the credential. Up to 255 characters. + +- `metadata: Optional[Dict[str, str]]` + + Arbitrary key-value metadata to attach to the credential. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.create( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", + auth={ + "token": "bearer_exampletoken", + "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", + "type": "static_bearer", + }, +) +print(beta_managed_agents_credential.id) +``` diff --git a/content/en/api/python/beta/vaults/credentials/delete.md b/content/en/api/python/beta/vaults/credentials/delete.md new file mode 100644 index 000000000..2d41aed43 --- /dev/null +++ b/content/en/api/python/beta/vaults/credentials/delete.md @@ -0,0 +1,93 @@ +## Delete + +`beta.vaults.credentials.delete(strcredential_id, CredentialDeleteParams**kwargs) -> BetaManagedAgentsDeletedCredential` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedCredential: …` + + Confirmation of a deleted credential. + + - `id: str` + + Unique identifier of the deleted credential. + + - `type: Literal["vault_credential_deleted"]` + + - `"vault_credential_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_deleted_credential = client.beta.vaults.credentials.delete( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_deleted_credential.id) +``` diff --git a/content/en/api/python/beta/vaults/credentials/list.md b/content/en/api/python/beta/vaults/credentials/list.md new file mode 100644 index 000000000..854ab92be --- /dev/null +++ b/content/en/api/python/beta/vaults/credentials/list.md @@ -0,0 +1,207 @@ +## List + +`beta.vaults.credentials.list(strvault_id, CredentialListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsCredential]` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vault_id: str` + +- `include_archived: Optional[bool]` + + Whether to include archived credentials in the results. + +- `limit: Optional[int]` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination token from a previous `list_credentials` response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.vaults.credentials.list( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +page = page.data[0] +print(page.id) +``` diff --git a/content/en/api/python/beta/vaults/credentials/retrieve.md b/content/en/api/python/beta/vaults/credentials/retrieve.md new file mode 100644 index 000000000..e83412a13 --- /dev/null +++ b/content/en/api/python/beta/vaults/credentials/retrieve.md @@ -0,0 +1,197 @@ +## Retrieve + +`beta.vaults.credentials.retrieve(strcredential_id, CredentialRetrieveParams**kwargs) -> BetaManagedAgentsCredential` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.retrieve( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_credential.id) +``` diff --git a/content/en/api/python/beta/vaults/credentials/update.md b/content/en/api/python/beta/vaults/credentials/update.md new file mode 100644 index 000000000..40006fd50 --- /dev/null +++ b/content/en/api/python/beta/vaults/credentials/update.md @@ -0,0 +1,277 @@ +## Update + +`beta.vaults.credentials.update(strcredential_id, CredentialUpdateParams**kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `vault_id: str` + +- `credential_id: str` + +- `auth: Optional[Auth]` + + Updated authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthUpdateParams: …` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `access_token: Optional[str]` + + Updated OAuth access token. + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshUpdateParams]` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: Optional[str]` + + Updated OAuth refresh token. + + - `scope: Optional[str]` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: Optional[TokenEndpointAuth]` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam: …` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam: …` + + Updated POST body authentication parameters for the token endpoint. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `client_secret: Optional[str]` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams: …` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `token: Optional[str]` + + Updated static bearer token value. + +- `display_name: Optional[str]` + + Updated human-readable name for the credential. 1-255 characters. + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential: …` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: str` + + Unique identifier for the credential. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `auth: Auth` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse: …` + + OAuth credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["mcp_oauth"]` + + - `"mcp_oauth"` + + - `expires_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `refresh: Optional[BetaManagedAgentsMCPOAuthRefreshResponse]` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: str` + + OAuth client ID. + + - `token_endpoint: str` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: TokenEndpointAuth` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse: …` + + Token endpoint requires no client authentication. + + - `type: Literal["none"]` + + - `"none"` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse: …` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: Literal["client_secret_basic"]` + + - `"client_secret_basic"` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse: …` + + Token endpoint uses POST body authentication with client credentials. + + - `type: Literal["client_secret_post"]` + + - `"client_secret_post"` + + - `resource: Optional[str]` + + OAuth resource indicator. + + - `scope: Optional[str]` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse: …` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: str` + + URL of the MCP server this credential authenticates against. + + - `type: Literal["static_bearer"]` + + - `"static_bearer"` + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the credential. + + - `type: Literal["vault_credential"]` + + - `"vault_credential"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + + - `vault_id: str` + + Identifier of the vault this credential belongs to. + + - `display_name: Optional[str]` + + Human-readable name for the credential. + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_credential = client.beta.vaults.credentials.update( + credential_id="vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_credential.id) +``` diff --git a/content/en/api/python/beta/vaults/delete.md b/content/en/api/python/beta/vaults/delete.md new file mode 100644 index 000000000..963f70a8a --- /dev/null +++ b/content/en/api/python/beta/vaults/delete.md @@ -0,0 +1,90 @@ +## Delete + +`beta.vaults.delete(strvault_id, VaultDeleteParams**kwargs) -> BetaManagedAgentsDeletedVault` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `vault_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedVault: …` + + Confirmation of a deleted vault. + + - `id: str` + + Unique identifier of the deleted vault. + + - `type: Literal["vault_deleted"]` + + - `"vault_deleted"` + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_deleted_vault = client.beta.vaults.delete( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_deleted_vault.id) +``` diff --git a/content/en/api/python/beta/vaults/list.md b/content/en/api/python/beta/vaults/list.md new file mode 100644 index 000000000..ae8690d34 --- /dev/null +++ b/content/en/api/python/beta/vaults/list.md @@ -0,0 +1,119 @@ +## List + +`beta.vaults.list(VaultListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsVault]` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `include_archived: Optional[bool]` + + Whether to include archived vaults in the results. + +- `limit: Optional[int]` + + Maximum number of vaults to return per page. Defaults to 20, maximum 100. + +- `page: Optional[str]` + + Opaque pagination token from a previous `list_vaults` response. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +page = client.beta.vaults.list() +page = page.data[0] +print(page.id) +``` diff --git a/content/en/api/python/beta/vaults/retrieve.md b/content/en/api/python/beta/vaults/retrieve.md new file mode 100644 index 000000000..e01ed571b --- /dev/null +++ b/content/en/api/python/beta/vaults/retrieve.md @@ -0,0 +1,110 @@ +## Retrieve + +`beta.vaults.retrieve(strvault_id, VaultRetrieveParams**kwargs) -> BetaManagedAgentsVault` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `vault_id: str` + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_vault = client.beta.vaults.retrieve( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_vault.id) +``` diff --git a/content/en/api/python/beta/vaults/update.md b/content/en/api/python/beta/vaults/update.md new file mode 100644 index 000000000..e9657afbc --- /dev/null +++ b/content/en/api/python/beta/vaults/update.md @@ -0,0 +1,118 @@ +## Update + +`beta.vaults.update(strvault_id, VaultUpdateParams**kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `vault_id: str` + +- `display_name: Optional[str]` + + Updated human-readable name for the vault. 1-255 characters. + +- `metadata: Optional[Dict[str, Optional[str]]]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Optional[List[AnthropicBetaParam]]` + + Optional header to specify the beta version(s) you want to use. + + - `str` + + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault: …` + + A vault that stores credentials for use by agents during sessions. + + - `id: str` + + Unique identifier for the vault. + + - `archived_at: Optional[datetime]` + + A timestamp in RFC 3339 format + + - `created_at: datetime` + + A timestamp in RFC 3339 format + + - `display_name: str` + + Human-readable name for the vault. + + - `metadata: Dict[str, str]` + + Arbitrary key-value metadata attached to the vault. + + - `type: Literal["vault"]` + + - `"vault"` + + - `updated_at: datetime` + + A timestamp in RFC 3339 format + +### Example + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), # This is the default and can be omitted +) +beta_managed_agents_vault = client.beta.vaults.update( + vault_id="vlt_011CZkZDLs7fYzm1hXNPeRjv", +) +print(beta_managed_agents_vault.id) +``` diff --git a/content/en/api/python/completions.md b/content/en/api/python/completions.md index 903a9f0c2..599c1aa1a 100644 --- a/content/en/api/python/completions.md +++ b/content/en/api/python/completions.md @@ -26,13 +26,14 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -48,9 +49,13 @@ Future models and features will not be compatible with Text Completions. See our - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -186,7 +191,7 @@ Future models and features will not be compatible with Text Completions. See our - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -230,8 +235,6 @@ Future models and features will not be compatible with Text Completions. See our - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class Completion: …` @@ -252,13 +255,14 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -274,9 +278,13 @@ Future models and features will not be compatible with Text Completions. See our - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -364,7 +372,7 @@ client = Anthropic( ) for completion in client.completions.create( max_tokens_to_sample=256, - model="claude-opus-4-6", + model="claude-mythos-preview", prompt="\n\nHuman: Hello, world!\n\nAssistant:", ): print(completion) @@ -392,13 +400,14 @@ for completion in client.completions.create( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -414,9 +423,13 @@ for completion in client.completions.create( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/python/completions/create.md b/content/en/api/python/completions/create.md index 94f23ae08..e61960d54 100644 --- a/content/en/api/python/completions/create.md +++ b/content/en/api/python/completions/create.md @@ -24,13 +24,14 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -46,9 +47,13 @@ Future models and features will not be compatible with Text Completions. See our - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -184,7 +189,7 @@ Future models and features will not be compatible with Text Completions. See our - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -228,8 +233,6 @@ Future models and features will not be compatible with Text Completions. See our - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class Completion: …` @@ -250,13 +253,14 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -272,9 +276,13 @@ Future models and features will not be compatible with Text Completions. See our - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -362,7 +370,7 @@ client = Anthropic( ) for completion in client.completions.create( max_tokens_to_sample=256, - model="claude-opus-4-6", + model="claude-mythos-preview", prompt="\n\nHuman: Hello, world!\n\nAssistant:", ): print(completion) diff --git a/content/en/api/python/messages.md b/content/en/api/python/messages.md index 712d03af3..bf7ad2bc1 100644 --- a/content/en/api/python/messages.md +++ b/content/en/api/python/messages.md @@ -2305,13 +2305,14 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -2327,9 +2328,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4550,13 +4555,14 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -4572,9 +4578,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -7090,13 +7100,14 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -7112,9 +7123,13 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -8576,7 +8591,7 @@ message_tokens_count = client.messages.count_tokens( "content": "string", "role": "user", }], - model="claude-opus-4-6", + model="claude-mythos-preview", ) print(message_tokens_count.input_tokens) ``` @@ -14271,13 +14286,14 @@ print(message_tokens_count.input_tokens) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -14293,9 +14309,13 @@ print(message_tokens_count.input_tokens) - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -17818,19 +17838,20 @@ print(message_tokens_count.input_tokens) ### Model -- `Union[Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more], str]` +- `Union[Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more], str]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -17846,9 +17867,13 @@ print(message_tokens_count.input_tokens) - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -19715,13 +19740,14 @@ print(message_tokens_count.input_tokens) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -19737,9 +19763,13 @@ print(message_tokens_count.input_tokens) - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -20667,13 +20697,14 @@ print(message_tokens_count.input_tokens) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -20689,9 +20720,13 @@ print(message_tokens_count.input_tokens) - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -29778,13 +29813,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -29800,9 +29836,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -32595,13 +32635,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -32617,9 +32658,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -33882,13 +33927,14 @@ for batch in client.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -33904,9 +33950,13 @@ for batch in client.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -34962,13 +35012,14 @@ for batch in client.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -34984,9 +35035,13 @@ for batch in client.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -36004,13 +36059,14 @@ for batch in client.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -36026,9 +36082,13 @@ for batch in client.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/python/messages/batches.md b/content/en/api/python/messages/batches.md index a9eedf8a9..1a1ca9e64 100644 --- a/content/en/api/python/messages/batches.md +++ b/content/en/api/python/messages/batches.md @@ -2321,13 +2321,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -2343,9 +2344,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -5138,13 +5143,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -5160,9 +5166,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -6425,13 +6435,14 @@ for batch in client.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -6447,9 +6458,13 @@ for batch in client.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -7505,13 +7520,14 @@ for batch in client.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -7527,9 +7543,13 @@ for batch in client.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -8547,13 +8567,14 @@ for batch in client.messages.batches.results( See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -8569,9 +8590,13 @@ for batch in client.messages.batches.results( - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/python/messages/batches/create.md b/content/en/api/python/messages/batches/create.md index 04abee270..e504825df 100644 --- a/content/en/api/python/messages/batches/create.md +++ b/content/en/api/python/messages/batches/create.md @@ -2319,13 +2319,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -2341,9 +2342,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/python/messages/batches/results.md b/content/en/api/python/messages/batches/results.md index 6320c8324..b2346da08 100644 --- a/content/en/api/python/messages/batches/results.md +++ b/content/en/api/python/messages/batches/results.md @@ -747,13 +747,14 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -769,9 +770,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/python/messages/count_tokens.md b/content/en/api/python/messages/count_tokens.md index cf20e0ded..09a3f6a48 100644 --- a/content/en/api/python/messages/count_tokens.md +++ b/content/en/api/python/messages/count_tokens.md @@ -2295,13 +2295,14 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -2317,9 +2318,13 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -3781,7 +3786,7 @@ message_tokens_count = client.messages.count_tokens( "content": "string", "role": "user", }], - model="claude-opus-4-6", + model="claude-mythos-preview", ) print(message_tokens_count.input_tokens) ``` diff --git a/content/en/api/python/messages/create.md b/content/en/api/python/messages/create.md index e2d944652..3763e26b7 100644 --- a/content/en/api/python/messages/create.md +++ b/content/en/api/python/messages/create.md @@ -2303,13 +2303,14 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -2325,9 +2326,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4548,13 +4553,14 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `Literal["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", 12 more]` + - `Literal["claude-mythos-preview", "claude-opus-4-6", "claude-sonnet-4-6", 13 more]` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `claude-opus-4-6` - Most intelligent model for building agents and coding + - `claude-mythos-preview` - New class of intelligence, strongest in coding and cybersecurity + - `claude-opus-4-6` - Frontier intelligence for long-running agents and coding - `claude-sonnet-4-6` - Best combination of speed and intelligence - `claude-haiku-4-5` - Fastest model with near-frontier intelligence - `claude-haiku-4-5-20251001` - Fastest model with near-frontier intelligence @@ -4570,9 +4576,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `claude-sonnet-4-20250514` - High-performance model with extended thinking - `claude-3-haiku-20240307` - Deprecated: Will reach end-of-life on April 20th, 2026. Please migrate to claude-haiku-4-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/python/models.md b/content/en/api/python/models.md index 92b33cde7..885c09937 100644 --- a/content/en/api/python/models.md +++ b/content/en/api/python/models.md @@ -32,7 +32,7 @@ The Models API response can be used to determine which models are available for - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -76,8 +76,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class ModelInfo: …` @@ -298,7 +296,7 @@ The Models API response can be used to determine information about a specific mo - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -342,8 +340,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class ModelInfo: …` diff --git a/content/en/api/python/models/list.md b/content/en/api/python/models/list.md index 3e489433d..8f88ac217 100644 --- a/content/en/api/python/models/list.md +++ b/content/en/api/python/models/list.md @@ -30,7 +30,7 @@ The Models API response can be used to determine which models are available for - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class ModelInfo: …` diff --git a/content/en/api/python/models/retrieve.md b/content/en/api/python/models/retrieve.md index b7c7a9308..7d65e9f60 100644 --- a/content/en/api/python/models/retrieve.md +++ b/content/en/api/python/models/retrieve.md @@ -20,7 +20,7 @@ The Models API response can be used to determine information about a specific mo - `str` - - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 19 more]` + - `Literal["message-batches-2024-09-24", "prompt-caching-2024-07-31", "computer-use-2024-10-22", 18 more]` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `class ModelInfo: …` diff --git a/content/en/api/rate-limits.md b/content/en/api/rate-limits.md index 220dcb420..77f5bb006 100644 --- a/content/en/api/rate-limits.md +++ b/content/en/api/rate-limits.md @@ -259,6 +259,15 @@ If you're seeking higher limits for an Enterprise use case, contact sales throug
                                                                                                                                                                                                                                                                                                                                                                                    +### Managed Agents + +[Claude Managed Agents](/docs/en/managed-agents/overview) endpoints are rate-limited per organization. These limits are separate from the Messages API rate limits above. + +| Operation | Limit | +| --- | --- | +| Create endpoints (agents, sessions, environments, etc.) | 60 requests per minute | +| Read endpoints (retrieve, list, stream, etc.) | 600 requests per minute | + ### Fast mode rate limits When using [fast mode](/docs/en/build-with-claude/fast-mode) (beta: research preview) with `speed: "fast"` on Opus 4.6, dedicated rate limits apply that are separate from standard Opus rate limits. When fast mode rate limits are exceeded, the API returns a `429` error with a `retry-after` header. diff --git a/content/en/api/ruby/beta.md b/content/en/api/ruby/beta.md index 50797a9f3..e758d5d28 100644 --- a/content/en/api/ruby/beta.md +++ b/content/en/api/ruby/beta.md @@ -4,11 +4,11 @@ ### Anthropic Beta -- `AnthropicBeta = String | :"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` +- `AnthropicBeta = String | :"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -52,8 +52,6 @@ - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Beta API Error - `class BetaAPIError` @@ -338,7 +336,7 @@ The Models API response can be used to determine which models are available for - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -382,8 +380,6 @@ The Models API response can be used to determine which models are available for - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaModelInfo` @@ -602,7 +598,7 @@ The Models API response can be used to determine information about a specific mo - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -646,8 +642,6 @@ The Models API response can be used to determine information about a specific mo - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaModelInfo` @@ -3923,15 +3917,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -6000,17 +5998,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. -- `user_profile_id: String` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Array[AnthropicBeta]` Optional header to specify the beta version(s) you want to use. - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -6054,8 +6048,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessage` @@ -6979,15 +6971,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -9891,15 +9887,19 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -11878,7 +11878,7 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -11922,8 +11922,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageTokensCount` @@ -11949,7 +11947,7 @@ anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") beta_message_tokens_count = anthropic.beta.messages.count_tokens( messages: [{content: "string", role: :user}], - model: :"claude-opus-4-6" + model: :"claude-mythos-preview" ) puts(beta_message_tokens_count) @@ -19140,15 +19138,19 @@ puts(beta_message_tokens_count) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -24484,15 +24486,19 @@ puts(beta_message_tokens_count) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -25728,15 +25734,19 @@ puts(beta_message_tokens_count) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -34277,7 +34287,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Must be unique for each request within the Message Batch. - - `params: { max_tokens, messages, model, 20 more}` + - `params: { max_tokens, messages, model, 19 more}` Messages API creation parameters for the individual request. @@ -36868,15 +36878,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -38945,17 +38959,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id: String` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Array[AnthropicBeta]` Optional header to specify the beta version(s) you want to use. - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -38999,8 +39009,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` @@ -39132,7 +39140,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -39176,8 +39184,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` @@ -39312,7 +39318,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -39356,8 +39362,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` @@ -39484,7 +39488,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -39528,8 +39532,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` @@ -39656,7 +39658,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -39700,8 +39702,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaDeletedMessageBatch` @@ -39754,7 +39754,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -39798,8 +39798,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatchIndividualResponse` @@ -40741,15 +40739,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -42317,15 +42319,19 @@ puts(beta_message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -43689,15 +43695,19 @@ puts(beta_message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -45023,15 +45033,19 @@ puts(beta_message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -45332,345 +45346,387 @@ puts(beta_message_batch_individual_response) - `:succeeded` -# Files +# Agents -## Upload +## Create -`beta.files.upload(**kwargs) -> FileMetadata` +`beta.agents.create(**kwargs) -> BetaManagedAgentsAgent` -**post** `/v1/files` +**post** `/v1/agents` -Upload File +Create Agent ### Parameters -- `file: String` +- `model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` - The file to upload + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control -- `betas: Array[AnthropicBeta]` + - `BetaManagedAgentsModel = :"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more | String` - Optional header to specify the beta version(s) you want to use. + The model that will power your agent. - - `String` + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` - - `:"message-batches-2024-09-24"` + The model that will power your agent. - - `:"prompt-caching-2024-07-31"` + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"computer-use-2024-10-22"` + - `:"claude-opus-4-6"` - - `:"computer-use-2025-01-24"` + Most intelligent model for building agents and coding - - `:"pdfs-2024-09-25"` + - `:"claude-sonnet-4-6"` - - `:"token-counting-2024-11-01"` + Best combination of speed and intelligence - - `:"token-efficient-tools-2025-02-19"` + - `:"claude-haiku-4-5"` - - `:"output-128k-2025-02-19"` + Fastest model with near-frontier intelligence - - `:"files-api-2025-04-14"` + - `:"claude-haiku-4-5-20251001"` - - `:"mcp-client-2025-04-04"` + Fastest model with near-frontier intelligence - - `:"mcp-client-2025-11-20"` + - `:"claude-opus-4-5"` - - `:"dev-full-thinking-2025-05-14"` + Premium model combining maximum intelligence with practical performance - - `:"interleaved-thinking-2025-05-14"` + - `:"claude-opus-4-5-20251101"` - - `:"code-execution-2025-05-22"` + Premium model combining maximum intelligence with practical performance - - `:"extended-cache-ttl-2025-04-11"` + - `:"claude-sonnet-4-5"` - - `:"context-1m-2025-08-07"` + High-performance model for agents and coding - - `:"context-management-2025-06-27"` + - `:"claude-sonnet-4-5-20250929"` - - `:"model-context-window-exceeded-2025-08-26"` + High-performance model for agents and coding - - `:"skills-2025-10-02"` + - `String` - - `:"fast-mode-2026-02-01"` + - `class BetaManagedAgentsModelConfigParams` - - `:"output-300k-2026-03-24"` + An object that defines additional configuration control over model use - - `:"user-profiles-2026-03-24"` + - `id: BetaManagedAgentsModel` -### Returns + The model that will power your agent. -- `class FileMetadata` + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `id: String` + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` - Unique object identifier. + The model that will power your agent. - The format and length of IDs may change over time. + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `created_at: Time` + - `:"claude-opus-4-6"` - RFC 3339 datetime string representing when the file was created. + Most intelligent model for building agents and coding - - `filename: String` + - `:"claude-sonnet-4-6"` - Original filename of the uploaded file. + Best combination of speed and intelligence - - `mime_type: String` + - `:"claude-haiku-4-5"` - MIME type of the file. + Fastest model with near-frontier intelligence - - `size_bytes: Integer` + - `:"claude-haiku-4-5-20251001"` - Size of the file in bytes. + Fastest model with near-frontier intelligence - - `type: :file` + - `:"claude-opus-4-5"` - Object type. + Premium model combining maximum intelligence with practical performance - For files, this is always `"file"`. + - `:"claude-opus-4-5-20251101"` - - `:file` + Premium model combining maximum intelligence with practical performance - - `downloadable: bool` + - `:"claude-sonnet-4-5"` - Whether the file can be downloaded. + High-performance model for agents and coding -### Example + - `:"claude-sonnet-4-5-20250929"` -```ruby -require "anthropic" + High-performance model for agents and coding -anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + - `String` -file_metadata = anthropic.beta.files.upload(file: StringIO.new("Example data")) + - `speed: :standard | :fast` -puts(file_metadata) -``` + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. -## List + - `:standard` -`beta.files.list(**kwargs) -> Page` + - `:fast` -**get** `/v1/files` +- `name: String` -List Files + Human-readable name for the agent. 1-256 characters. -### Parameters +- `description: String` -- `after_id: String` + Description of what the agent does. Up to 2048 characters. - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. +- `mcp_servers: Array[BetaManagedAgentsURLMCPServerParams]` -- `before_id: String` + MCP servers this agent connects to. Maximum 20. Names must be unique within the array. - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + - `name: String` -- `limit: Integer` + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. - Number of items to return per page. + - `type: :url` - Defaults to `20`. Ranges from `1` to `1000`. + - `:url` -- `betas: Array[AnthropicBeta]` + - `url: String` - Optional header to specify the beta version(s) you want to use. + Endpoint URL for the MCP server. - - `String` +- `metadata: Hash[Symbol, String]` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - - `:"message-batches-2024-09-24"` +- `skills: Array[BetaManagedAgentsSkillParams]` - - `:"prompt-caching-2024-07-31"` + Skills available to the agent. Maximum 20. - - `:"computer-use-2024-10-22"` + - `class BetaManagedAgentsAnthropicSkillParams` - - `:"computer-use-2025-01-24"` + An Anthropic-managed skill. - - `:"pdfs-2024-09-25"` + - `skill_id: String` - - `:"token-counting-2024-11-01"` + Identifier of the Anthropic skill (e.g., "xlsx"). - - `:"token-efficient-tools-2025-02-19"` + - `type: :anthropic` - - `:"output-128k-2025-02-19"` + - `:anthropic` - - `:"files-api-2025-04-14"` + - `version: String` - - `:"mcp-client-2025-04-04"` + Version to pin. Defaults to latest if omitted. - - `:"mcp-client-2025-11-20"` + - `class BetaManagedAgentsCustomSkillParams` - - `:"dev-full-thinking-2025-05-14"` + A user-created custom skill. - - `:"interleaved-thinking-2025-05-14"` + - `skill_id: String` - - `:"code-execution-2025-05-22"` + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). - - `:"extended-cache-ttl-2025-04-11"` + - `type: :custom` - - `:"context-1m-2025-08-07"` + - `:custom` - - `:"context-management-2025-06-27"` + - `version: String` - - `:"model-context-window-exceeded-2025-08-26"` + Version to pin. Defaults to latest if omitted. - - `:"skills-2025-10-02"` +- `system_: String` - - `:"fast-mode-2026-02-01"` + System prompt for the agent. Up to 100,000 characters. - - `:"output-300k-2026-03-24"` +- `tools: Array[BetaManagedAgentsAgentToolset20260401Params | BetaManagedAgentsMCPToolsetParams | BetaManagedAgentsCustomToolParams]` - - `:"user-profiles-2026-03-24"` + Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. -### Returns + - `class BetaManagedAgentsAgentToolset20260401Params` -- `class FileMetadata` + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. - - `id: String` + - `type: :agent_toolset_20260401` - Unique object identifier. + - `:agent_toolset_20260401` - The format and length of IDs may change over time. + - `configs: Array[BetaManagedAgentsAgentToolConfigParams]` - - `created_at: Time` + Per-tool configuration overrides. - RFC 3339 datetime string representing when the file was created. + - `name: :bash | :edit | :read | 5 more` - - `filename: String` + Built-in agent tool identifier. - Original filename of the uploaded file. + - `:bash` - - `mime_type: String` + - `:edit` - MIME type of the file. + - `:read` - - `size_bytes: Integer` + - `:write` - Size of the file in bytes. + - `:glob` - - `type: :file` + - `:grep` - Object type. + - `:web_fetch` - For files, this is always `"file"`. + - `:web_search` - - `:file` + - `enabled: bool` - - `downloadable: bool` + Whether this tool is enabled and available to Claude. Overrides the default_config setting. - Whether the file can be downloaded. + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` -### Example + Permission policy for tool execution. -```ruby -require "anthropic" + - `class BetaManagedAgentsAlwaysAllowPolicy` -anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + Tool calls are automatically approved without user confirmation. -page = anthropic.beta.files.list + - `type: :always_allow` -puts(page) -``` + - `:always_allow` -## Download + - `class BetaManagedAgentsAlwaysAskPolicy` -`beta.files.download(file_id, **kwargs) -> StringIO` + Tool calls require user confirmation before execution. -**get** `/v1/files/{file_id}/content` + - `type: :always_ask` -Download File + - `:always_ask` -### Parameters + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfigParams` -- `file_id: String` + Default configuration for all tools in a toolset. - ID of the File. + - `enabled: bool` -- `betas: Array[AnthropicBeta]` + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - Optional header to specify the beta version(s) you want to use. + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` - - `String` + Permission policy for tool execution. - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `class BetaManagedAgentsAlwaysAllowPolicy` - - `:"message-batches-2024-09-24"` + Tool calls are automatically approved without user confirmation. - - `:"prompt-caching-2024-07-31"` + - `type: :always_allow` - - `:"computer-use-2024-10-22"` + - `:always_allow` - - `:"computer-use-2025-01-24"` + - `class BetaManagedAgentsAlwaysAskPolicy` - - `:"pdfs-2024-09-25"` + Tool calls require user confirmation before execution. - - `:"token-counting-2024-11-01"` + - `type: :always_ask` - - `:"token-efficient-tools-2025-02-19"` + - `:always_ask` - - `:"output-128k-2025-02-19"` + - `class BetaManagedAgentsMCPToolsetParams` - - `:"files-api-2025-04-14"` + Configuration for tools from an MCP server defined in `mcp_servers`. - - `:"mcp-client-2025-04-04"` + - `mcp_server_name: String` - - `:"mcp-client-2025-11-20"` + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. - - `:"dev-full-thinking-2025-05-14"` + - `type: :mcp_toolset` - - `:"interleaved-thinking-2025-05-14"` + - `:mcp_toolset` - - `:"code-execution-2025-05-22"` + - `configs: Array[BetaManagedAgentsMCPToolConfigParams]` - - `:"extended-cache-ttl-2025-04-11"` + Per-tool configuration overrides. - - `:"context-1m-2025-08-07"` + - `name: String` - - `:"context-management-2025-06-27"` + Name of the MCP tool to configure. 1-128 characters. - - `:"model-context-window-exceeded-2025-08-26"` + - `enabled: bool` - - `:"skills-2025-10-02"` + Whether this tool is enabled. Overrides the `default_config` setting. - - `:"fast-mode-2026-02-01"` + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` - - `:"output-300k-2026-03-24"` + Permission policy for tool execution. - - `:"user-profiles-2026-03-24"` + - `class BetaManagedAgentsAlwaysAllowPolicy` -### Returns + Tool calls are automatically approved without user confirmation. -- `StringIO` + - `type: :always_allow` -### Example + - `:always_allow` -```ruby -require "anthropic" + - `class BetaManagedAgentsAlwaysAskPolicy` -anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + Tool calls require user confirmation before execution. -response = anthropic.beta.files.download("file_id") + - `type: :always_ask` -puts(response) -``` + - `:always_ask` -## Retrieve Metadata + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfigParams` -`beta.files.retrieve_metadata(file_id, **kwargs) -> FileMetadata` + Default configuration for all tools from an MCP server. -**get** `/v1/files/{file_id}` + - `enabled: bool` -Get File Metadata + Whether tools are enabled by default. Defaults to true if not specified. -### Parameters + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` -- `file_id: String` + Permission policy for tool execution. - ID of the File. + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `class BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: String` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: :custom` + + - `:custom` - `betas: Array[AnthropicBeta]` @@ -45678,7 +45734,7 @@ Get File Metadata - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -45722,7 +45778,22835 @@ Get File Metadata - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_agent = anthropic.beta.agents.create(model: :"claude-sonnet-4-6", name: "My First Agent") + +puts(beta_managed_agents_agent) +``` + +## List + +`beta.agents.list(**kwargs) -> PageCursor` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `created_at_gte: Time` + + Return agents created at or after this time (inclusive). + +- `created_at_lte: Time` + + Return agents created at or before this time (inclusive). + +- `include_archived: bool` + + Include archived agents in results. Defaults to false. + +- `limit: Integer` + + Maximum results per page. Default 20, maximum 100. + +- `page: String` + + Opaque pagination cursor from a previous response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.agents.list + +puts(page) +``` + +## Retrieve + +`beta.agents.retrieve(agent_id, **kwargs) -> BetaManagedAgentsAgent` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `agent_id: String` + +- `version: Integer` + + Agent version. Omit for the most recent version. Must be at least 1 if specified. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_agent = anthropic.beta.agents.retrieve("agent_011CZkYpogX7uDKUyvBTophP") + +puts(beta_managed_agents_agent) +``` + +## Update + +`beta.agents.update(agent_id, **kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `agent_id: String` + +- `version: Integer` + + The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + +- `description: String` + + Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + +- `mcp_servers: Array[BetaManagedAgentsURLMCPServerParams]` + + MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `name: String` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: :url` + + - `:url` + + - `url: String` + + Endpoint URL for the MCP server. + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + +- `model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `BetaManagedAgentsModel = :"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more | String` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `class BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + +- `name: String` + + Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + +- `skills: Array[BetaManagedAgentsSkillParams]` + + Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: String` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: String` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: :custom` + + - `:custom` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + +- `system_: String` + + System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + +- `tools: Array[BetaManagedAgentsAgentToolset20260401Params | BetaManagedAgentsMCPToolsetParams | BetaManagedAgentsCustomToolParams]` + + Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfigParams]` + + Per-tool configuration overrides. + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `enabled: bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `class BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: String` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfigParams]` + + Per-tool configuration overrides. + + - `name: String` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `class BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: String` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: :custom` + + - `:custom` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_agent = anthropic.beta.agents.update("agent_011CZkYpogX7uDKUyvBTophP", version: 1) + +puts(beta_managed_agents_agent) +``` + +## Archive + +`beta.agents.archive(agent_id, **kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `agent_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_agent = anthropic.beta.agents.archive("agent_011CZkYpogX7uDKUyvBTophP") + +puts(beta_managed_agents_agent) +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `class BetaManagedAgentsAgentToolConfig` + + Configuration for a specific agent tool. + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Agent Tool Config Params + +- `class BetaManagedAgentsAgentToolConfigParams` + + Configuration override for a specific tool within a toolset. + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `enabled: bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Agent Toolset Default Config + +- `class BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `class BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Agent Toolset20260401 + +- `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `class BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfigParams]` + + Per-tool configuration overrides. + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `enabled: bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Always Allow Policy + +- `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + +### Beta Managed Agents Always Ask Policy + +- `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Anthropic Skill + +- `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + +### Beta Managed Agents Anthropic Skill Params + +- `class BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: String` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + +### Beta Managed Agents Custom Skill Params + +- `class BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: String` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: :custom` + + - `:custom` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + +### Beta Managed Agents Custom Tool Input Schema + +- `class BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + +### Beta Managed Agents Custom Tool Params + +- `class BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: String` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: :custom` + + - `:custom` + +### Beta Managed Agents MCP Server URL Definition + +- `class BetaManagedAgentsMCPServerURLDefinition` + + URL-based MCP server connection as returned in API responses. + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + +### Beta Managed Agents MCP Tool Config + +- `class BetaManagedAgentsMCPToolConfig` + + Resolved configuration for a specific MCP tool. + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents MCP Tool Config Params + +- `class BetaManagedAgentsMCPToolConfigParams` + + Configuration override for a specific MCP tool. + + - `name: String` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents MCP Toolset + +- `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + +### Beta Managed Agents MCP Toolset Default Config + +- `class BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `class BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents MCP Toolset Params + +- `class BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: String` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfigParams]` + + Per-tool configuration overrides. + + - `name: String` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Model + +- `BetaManagedAgentsModel = :"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more | String` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + +### Beta Managed Agents Model Config + +- `class BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + +### Beta Managed Agents Model Config Params + +- `class BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + +### Beta Managed Agents Skill Params + +- `BetaManagedAgentsSkillParams = BetaManagedAgentsAnthropicSkillParams | BetaManagedAgentsCustomSkillParams` + + Skill to load in the session container. + + - `class BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: String` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: String` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: :custom` + + - `:custom` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `class BetaManagedAgentsURLMCPServerParams` + + URL-based MCP server connection. + + - `name: String` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: :url` + + - `:url` + + - `url: String` + + Endpoint URL for the MCP server. + +# Versions + +## List + +`beta.agents.versions.list(agent_id, **kwargs) -> PageCursor` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agent_id: String` + +- `limit: Integer` + + Maximum results per page. Default 20, maximum 100. + +- `page: String` + + Opaque pagination cursor. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.agents.versions.list("agent_011CZkYpogX7uDKUyvBTophP") + +puts(page) +``` + +# Environments + +## Create + +`beta.environments.create(**kwargs) -> BetaEnvironment` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `name: String` + + Human-readable name for the environment + +- `config: BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `packages: BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + +- `description: String` + + Optional description of the environment + +- `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment = anthropic.beta.environments.create(name: "python-data-analysis") + +puts(beta_environment) +``` + +## List + +`beta.environments.list(**kwargs) -> PageCursor` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `include_archived: bool` + + Include archived environments in the response + +- `limit: Integer` + + Maximum number of environments to return + +- `page: String` + + Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.environments.list + +puts(page) +``` + +## Retrieve + +`beta.environments.retrieve(environment_id, **kwargs) -> BetaEnvironment` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `environment_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment = anthropic.beta.environments.retrieve("env_011CZkZ9X2dpNyB7HsEFoRfW") + +puts(beta_environment) +``` + +## Update + +`beta.environments.update(environment_id, **kwargs) -> BetaEnvironment` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `environment_id: String` + +- `config: BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `packages: BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + +- `description: String` + + Updated description of the environment + +- `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + +- `name: String` + + Updated name for the environment + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment = anthropic.beta.environments.update("env_011CZkZ9X2dpNyB7HsEFoRfW") + +puts(beta_environment) +``` + +## Delete + +`beta.environments.delete(environment_id, **kwargs) -> BetaEnvironmentDeleteResponse` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `environment_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironmentDeleteResponse` + + Response after deleting an environment. + + - `id: String` + + Environment identifier + + - `type: :environment_deleted` + + The type of response + + - `:environment_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment_delete_response = anthropic.beta.environments.delete("env_011CZkZ9X2dpNyB7HsEFoRfW") + +puts(beta_environment_delete_response) +``` + +## Archive + +`beta.environments.archive(environment_id, **kwargs) -> BetaEnvironment` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `environment_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment = anthropic.beta.environments.archive("env_011CZkZ9X2dpNyB7HsEFoRfW") + +puts(beta_environment) +``` + +## Domain Types + +### Beta Cloud Config + +- `class BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + +### Beta Cloud Config Params + +- `class BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `packages: BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + +### Beta Environment + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `class BetaEnvironmentDeleteResponse` + + Response after deleting an environment. + + - `id: String` + + Environment identifier + + - `type: :environment_deleted` + + The type of response + + - `:environment_deleted` + +### Beta Limited Network + +- `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + +### Beta Limited Network Params + +- `class BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + +### Beta Packages + +- `class BetaPackages` + + Packages (and their versions) available in this environment. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + +### Beta Packages Params + +- `class BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + +### Beta Unrestricted Network + +- `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + +# Sessions + +## Create + +`beta.sessions.create(**kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `agent: String | BetaManagedAgentsAgentParams` + + Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `String` + + - `class BetaManagedAgentsAgentParams` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: String` + + The `agent` ID. + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +- `environment_id: String` + + ID of the `environment` defining the container configuration for this session. + +- `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the session. + +- `resources: Array[BetaManagedAgentsGitHubRepositoryResourceParams | BetaManagedAgentsFileResourceParams]` + + Resources (e.g. repositories, files) to mount into the session's container. + + - `class BetaManagedAgentsGitHubRepositoryResourceParams` + + Mount a GitHub repository into the session's container. + + - `authorization_token: String` + + GitHub authorization token used to clone the repository. + + - `type: :github_repository` + + - `:github_repository` + + - `url: String` + + Github URL of the repository + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `mount_path: String` + + Mount path in the container. Defaults to `/workspace/`. + + - `class BetaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `mount_path: String` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `title: String` + + Human-readable session title. + +- `vault_ids: Array[String]` + + Vault IDs for stored credentials the agent can use during the session. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_session = anthropic.beta.sessions.create( + agent: "agent_011CZkYpogX7uDKUyvBTophP", + environment_id: "env_011CZkZ9X2dpNyB7HsEFoRfW" +) + +puts(beta_managed_agents_session) +``` + +## List + +`beta.sessions.list(**kwargs) -> PageCursor` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `agent_id: String` + + Filter sessions created with this agent ID. + +- `agent_version: Integer` + + Filter by agent version. Only applies when agent_id is also set. + +- `created_at_gt: Time` + + Return sessions created after this time (exclusive). + +- `created_at_gte: Time` + + Return sessions created at or after this time (inclusive). + +- `created_at_lt: Time` + + Return sessions created before this time (exclusive). + +- `created_at_lte: Time` + + Return sessions created at or before this time (inclusive). + +- `include_archived: bool` + + When true, includes archived sessions. Default: false (exclude archived). + +- `limit: Integer` + + Maximum number of results to return. + +- `order: :asc | :desc` + + Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `:asc` + + - `:desc` + +- `page: String` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.sessions.list + +puts(page) +``` + +## Retrieve + +`beta.sessions.retrieve(session_id, **kwargs) -> BetaManagedAgentsSession` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_session = anthropic.beta.sessions.retrieve("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_session) +``` + +## Update + +`beta.sessions.update(session_id, **kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `session_id: String` + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + +- `title: String` + + Human-readable session title. + +- `vault_ids: Array[String]` + + Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_session = anthropic.beta.sessions.update("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_session) +``` + +## Delete + +`beta.sessions.delete(session_id, **kwargs) -> BetaManagedAgentsDeletedSession` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedSession` + + Confirmation that a `session` has been permanently deleted. + + - `id: String` + + - `type: :session_deleted` + + - `:session_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_deleted_session = anthropic.beta.sessions.delete("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_deleted_session) +``` + +## Archive + +`beta.sessions.archive(session_id, **kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_session = anthropic.beta.sessions.archive("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_session) +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `class BetaManagedAgentsAgentParams` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: String` + + The `agent` ID. + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + +### Beta Managed Agents Cache Creation Usage + +- `class BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + +### Beta Managed Agents Deleted Session + +- `class BetaManagedAgentsDeletedSession` + + Confirmation that a `session` has been permanently deleted. + + - `id: String` + + - `type: :session_deleted` + + - `:session_deleted` + +### Beta Managed Agents File Resource Params + +- `class BetaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `mount_path: String` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `class BetaManagedAgentsGitHubRepositoryResourceParams` + + Mount a GitHub repository into the session's container. + + - `authorization_token: String` + + GitHub authorization token used to clone the repository. + + - `type: :github_repository` + + - `:github_repository` + + - `url: String` + + Github URL of the repository + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `mount_path: String` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `class BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + +### Beta Managed Agents Session Stats + +- `class BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `class BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + +# Events + +## List + +`beta.sessions.events.list(session_id, **kwargs) -> PageCursor` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `session_id: String` + +- `limit: Integer` + + Query parameter for limit + +- `order: :asc | :desc` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `:asc` + + - `:desc` + +- `page: String` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.sessions.events.list("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(page) +``` + +## Send + +`beta.sessions.events.send_(session_id, **kwargs) -> BetaManagedAgentsSendSessionEvents` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `session_id: String` + +- `events: Array[BetaManagedAgentsEventParams]` + + Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data: Array[BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | BetaManagedAgentsUserCustomToolResultEvent]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_send_session_events = anthropic.beta.sessions.events.send_( + "sesn_011CZkZAtmR3yMPDzynEDxu7", + events: [{content: [{text: "Where is my order #1234?", type: :text}], type: :"user.message"}] +) + +puts(beta_managed_agents_send_session_events) +``` + +## Stream + +`beta.sessions.events.stream(session_id, **kwargs) -> BetaManagedAgentsStreamSessionEvents` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_stream_session_events = anthropic.beta.sessions.events.stream("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_stream_session_events) +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + +### Beta Managed Agents Agent Message Event + +- `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + +### Beta Managed Agents Base64 Document Source + +- `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + +### Beta Managed Agents Base64 Image Source + +- `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + +### Beta Managed Agents Billing Error + +- `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + +### Beta Managed Agents Document Block + +- `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + +### Beta Managed Agents Event Params + +- `BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams | BetaManagedAgentsUserInterruptEventParams | BetaManagedAgentsUserToolConfirmationEventParams | BetaManagedAgentsUserCustomToolResultEventParams` + + Union type for event parameters that can be sent to a session. + + - `class BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + +### Beta Managed Agents File Image Source + +- `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + +### Beta Managed Agents Image Block + +- `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + +### Beta Managed Agents MCP Authentication Failed Error + +- `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + +### Beta Managed Agents MCP Connection Failed Error + +- `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + +### Beta Managed Agents Model Overloaded Error + +- `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + +### Beta Managed Agents Model Rate Limited Error + +- `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + +### Beta Managed Agents Model Request Failed Error + +- `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + +### Beta Managed Agents Plain Text Document Source + +- `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + +### Beta Managed Agents Retry Status Exhausted + +- `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + +### Beta Managed Agents Retry Status Retrying + +- `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + +### Beta Managed Agents Retry Status Terminal + +- `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + +### Beta Managed Agents Send Session Events + +- `class BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data: Array[BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | BetaManagedAgentsUserCustomToolResultEvent]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + +### Beta Managed Agents Session Error Event + +- `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + +### Beta Managed Agents Session Event + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + +### Beta Managed Agents Session Retries Exhausted + +- `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + +### Beta Managed Agents Session Status Idle Event + +- `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `class BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + +### Beta Managed Agents Stream Session Events + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Beta Managed Agents Text Block + +- `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + +### Beta Managed Agents Unknown Error + +- `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + +### Beta Managed Agents URL Document Source + +- `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `class BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `class BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `class BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `class BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`beta.sessions.resources.add(session_id, **kwargs) -> BetaManagedAgentsFileResource` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `session_id: String` + +- `file_id: String` + + ID of a previously uploaded file. + +- `type: :file` + + - `:file` + +- `mount_path: String` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_file_resource = anthropic.beta.sessions.resources.add( + "sesn_011CZkZAtmR3yMPDzynEDxu7", + file_id: "file_011CNha8iCJcU1wXNR6q4V8w", + type: :file +) + +puts(beta_managed_agents_file_resource) +``` + +## List + +`beta.sessions.resources.list(session_id, **kwargs) -> PageCursor` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `session_id: String` + +- `limit: Integer` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `page: String` + + Opaque cursor from a previous response's next_page field. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.sessions.resources.list("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(page) +``` + +## Retrieve + +`beta.sessions.resources.retrieve(resource_id, **kwargs) -> ResourceRetrieveResponse` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `session_id: String` + +- `resource_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +resource = anthropic.beta.sessions.resources.retrieve( + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id: "sesn_011CZkZAtmR3yMPDzynEDxu7" +) + +puts(resource) +``` + +## Update + +`beta.sessions.resources.update(resource_id, **kwargs) -> ResourceUpdateResponse` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `session_id: String` + +- `resource_id: String` + +- `authorization_token: String` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +resource = anthropic.beta.sessions.resources.update( + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id: "sesn_011CZkZAtmR3yMPDzynEDxu7", + authorization_token: "ghp_exampletoken" +) + +puts(resource) +``` + +## Delete + +`beta.sessions.resources.delete(resource_id, **kwargs) -> BetaManagedAgentsDeleteSessionResource` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `session_id: String` + +- `resource_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: String` + + - `type: :session_resource_deleted` + + - `:session_resource_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_delete_session_resource = anthropic.beta.sessions.resources.delete( + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id: "sesn_011CZkZAtmR3yMPDzynEDxu7" +) + +puts(beta_managed_agents_delete_session_resource) +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `class BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: String` + + - `type: :session_resource_deleted` + + - `:session_resource_deleted` + +### Beta Managed Agents File Resource + +- `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + +### Beta Managed Agents Session Resource + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Resource Retrieve Response + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Resource Update Response + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +# Vaults + +## Create + +`beta.vaults.create(**kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `display_name: String` + + Human-readable name for the vault. 1-255 characters. + +- `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata to attach to the vault. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_vault = anthropic.beta.vaults.create(display_name: "Example vault") + +puts(beta_managed_agents_vault) +``` + +## List + +`beta.vaults.list(**kwargs) -> PageCursor` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `include_archived: bool` + + Whether to include archived vaults in the results. + +- `limit: Integer` + + Maximum number of vaults to return per page. Defaults to 20, maximum 100. + +- `page: String` + + Opaque pagination token from a previous `list_vaults` response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.vaults.list + +puts(page) +``` + +## Retrieve + +`beta.vaults.retrieve(vault_id, **kwargs) -> BetaManagedAgentsVault` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `vault_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_vault = anthropic.beta.vaults.retrieve("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(beta_managed_agents_vault) +``` + +## Update + +`beta.vaults.update(vault_id, **kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `vault_id: String` + +- `display_name: String` + + Updated human-readable name for the vault. 1-255 characters. + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_vault = anthropic.beta.vaults.update("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(beta_managed_agents_vault) +``` + +## Delete + +`beta.vaults.delete(vault_id, **kwargs) -> BetaManagedAgentsDeletedVault` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `vault_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedVault` + + Confirmation of a deleted vault. + + - `id: String` + + Unique identifier of the deleted vault. + + - `type: :vault_deleted` + + - `:vault_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_deleted_vault = anthropic.beta.vaults.delete("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(beta_managed_agents_deleted_vault) +``` + +## Archive + +`beta.vaults.archive(vault_id, **kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `vault_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_vault = anthropic.beta.vaults.archive("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(beta_managed_agents_vault) +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `class BetaManagedAgentsDeletedVault` + + Confirmation of a deleted vault. + + - `id: String` + + Unique identifier of the deleted vault. + + - `type: :vault_deleted` + + - `:vault_deleted` + +### Beta Managed Agents Vault + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`beta.vaults.credentials.create(vault_id, **kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vault_id: String` + +- `auth: BetaManagedAgentsMCPOAuthCreateParams | BetaManagedAgentsStaticBearerCreateParams` + + Authentication details for creating a credential. + + - `class BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: String` + + OAuth access token. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: String` + + OAuth client ID. + + - `refresh_token: String` + + OAuth refresh token. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: String` + + Static bearer token value. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + +- `display_name: String` + + Human-readable name for the credential. Up to 255 characters. + +- `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata to attach to the credential. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.create( + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + auth: { + token: "bearer_exampletoken", + mcp_server_url: "https://example-server.modelcontextprotocol.io/sse", + type: :static_bearer + } +) + +puts(beta_managed_agents_credential) +``` + +## List + +`beta.vaults.credentials.list(vault_id, **kwargs) -> PageCursor` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vault_id: String` + +- `include_archived: bool` + + Whether to include archived credentials in the results. + +- `limit: Integer` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `page: String` + + Opaque pagination token from a previous `list_credentials` response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.vaults.credentials.list("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(page) +``` + +## Retrieve + +`beta.vaults.credentials.retrieve(credential_id, **kwargs) -> BetaManagedAgentsCredential` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.retrieve( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_credential) +``` + +## Update + +`beta.vaults.credentials.update(credential_id, **kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `auth: BetaManagedAgentsMCPOAuthUpdateParams | BetaManagedAgentsStaticBearerUpdateParams` + + Updated authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `access_token: String` + + Updated OAuth access token. + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: String` + + Updated OAuth refresh token. + + - `scope: String` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: :static_bearer` + + - `:static_bearer` + + - `token: String` + + Updated static bearer token value. + +- `display_name: String` + + Updated human-readable name for the credential. 1-255 characters. + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.update( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_credential) +``` + +## Delete + +`beta.vaults.credentials.delete(credential_id, **kwargs) -> BetaManagedAgentsDeletedCredential` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: String` + + Unique identifier of the deleted credential. + + - `type: :vault_credential_deleted` + + - `:vault_credential_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_deleted_credential = anthropic.beta.vaults.credentials.delete( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_deleted_credential) +``` + +## Archive + +`beta.vaults.credentials.archive(credential_id, **kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.archive( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_credential) +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `class BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: String` + + Unique identifier of the deleted credential. + + - `type: :vault_credential_deleted` + + - `:vault_credential_deleted` + +### Beta Managed Agents MCP OAuth Auth Response + +- `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `class BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: String` + + OAuth access token. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: String` + + OAuth client ID. + + - `refresh_token: String` + + OAuth refresh token. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `class BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: String` + + OAuth client ID. + + - `refresh_token: String` + + OAuth refresh token. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `class BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `class BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: String` + + Updated OAuth refresh token. + + - `scope: String` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `class BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `access_token: String` + + Updated OAuth access token. + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: String` + + Updated OAuth refresh token. + + - `scope: String` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + +### Beta Managed Agents Static Bearer Create Params + +- `class BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: String` + + Static bearer token value. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + +### Beta Managed Agents Static Bearer Update Params + +- `class BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: :static_bearer` + + - `:static_bearer` + + - `token: String` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. + +# Files + +## Upload + +`beta.files.upload(**kwargs) -> FileMetadata` + +**post** `/v1/files` + +Upload File + +### Parameters + +- `file: String` + + The file to upload + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class FileMetadata` + + - `id: String` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: Time` + + RFC 3339 datetime string representing when the file was created. + + - `filename: String` + + Original filename of the uploaded file. + + - `mime_type: String` + + MIME type of the file. + + - `size_bytes: Integer` + + Size of the file in bytes. + + - `type: :file` + + Object type. + + For files, this is always `"file"`. + + - `:file` + + - `downloadable: bool` + + Whether the file can be downloaded. + + - `scope: BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +file_metadata = anthropic.beta.files.upload(file: StringIO.new("Example data")) + +puts(file_metadata) +``` + +## List + +`beta.files.list(**kwargs) -> Page` + +**get** `/v1/files` + +List Files + +### Parameters + +- `after_id: String` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `before_id: String` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `limit: Integer` + + Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `scope_id: String` + + Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class FileMetadata` + + - `id: String` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `created_at: Time` + + RFC 3339 datetime string representing when the file was created. + + - `filename: String` + + Original filename of the uploaded file. + + - `mime_type: String` + + MIME type of the file. + + - `size_bytes: Integer` + + Size of the file in bytes. + + - `type: :file` + + Object type. + + For files, this is always `"file"`. + + - `:file` + + - `downloadable: bool` + + Whether the file can be downloaded. + + - `scope: BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.files.list + +puts(page) +``` + +## Download + +`beta.files.download(file_id, **kwargs) -> StringIO` + +**get** `/v1/files/{file_id}/content` + +Download File + +### Parameters + +- `file_id: String` + + ID of the File. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `StringIO` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +response = anthropic.beta.files.download("file_id") + +puts(response) +``` + +## Retrieve Metadata + +`beta.files.retrieve_metadata(file_id, **kwargs) -> FileMetadata` + +**get** `/v1/files/{file_id}` + +Get File Metadata + +### Parameters + +- `file_id: String` + + ID of the File. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` ### Returns @@ -45762,6 +68646,20 @@ Get File Metadata Whether the file can be downloaded. + - `scope: BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` + ### Example ```ruby @@ -45794,7 +68692,7 @@ Delete File - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -45838,8 +68736,6 @@ Delete File - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class DeletedFile` @@ -45870,6 +68766,20 @@ puts(deleted_file) ## Domain Types +### Beta File Scope + +- `class BetaFileScope` + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` + ### Deleted File - `class DeletedFile` @@ -45924,6 +68834,20 @@ puts(deleted_file) Whether the file can be downloaded. + - `scope: BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` + # Skills ## Create @@ -45954,7 +68878,7 @@ Create Skill - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -45998,8 +68922,6 @@ Create Skill - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class SkillCreateResponse` @@ -46094,7 +69016,7 @@ List Skills - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -46138,8 +69060,6 @@ List Skills - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class SkillListResponse` @@ -46219,7 +69139,7 @@ Get Skill - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -46263,8 +69183,6 @@ Get Skill - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class SkillRetrieveResponse` @@ -46344,7 +69262,7 @@ Delete Skill - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -46388,8 +69306,6 @@ Delete Skill - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class SkillDeleteResponse` @@ -46601,7 +69517,7 @@ Create Skill Version - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -46645,8 +69561,6 @@ Create Skill Version - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionCreateResponse` @@ -46739,7 +69653,7 @@ List Skill Versions - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -46783,8 +69697,6 @@ List Skill Versions - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionListResponse` @@ -46873,7 +69785,7 @@ Get Skill Version - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -46917,8 +69829,6 @@ Get Skill Version - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionRetrieveResponse` @@ -47007,7 +69917,7 @@ Delete Skill Version - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -47051,8 +69961,6 @@ Delete Skill Version - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionDeleteResponse` @@ -47242,561 +70150,3 @@ puts(version) Deleted object type. For Skill Versions, this is always `"skill_version_deleted"`. - -# User Profiles - -## Create - -`beta.user_profiles.create(**kwargs) -> BetaUserProfile` - -**post** `/v1/user_profiles` - -Create User Profile - -### Parameters - -- `external_id: String` - -- `metadata: Hash[Symbol, String]` - - Free-form key-value data to attach to this user profile. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. Values must be non-empty strings. - -- `betas: Array[AnthropicBeta]` - - Optional header to specify the beta version(s) you want to use. - - - `String` - - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` - - - `:"message-batches-2024-09-24"` - - - `:"prompt-caching-2024-07-31"` - - - `:"computer-use-2024-10-22"` - - - `:"computer-use-2025-01-24"` - - - `:"pdfs-2024-09-25"` - - - `:"token-counting-2024-11-01"` - - - `:"token-efficient-tools-2025-02-19"` - - - `:"output-128k-2025-02-19"` - - - `:"files-api-2025-04-14"` - - - `:"mcp-client-2025-04-04"` - - - `:"mcp-client-2025-11-20"` - - - `:"dev-full-thinking-2025-05-14"` - - - `:"interleaved-thinking-2025-05-14"` - - - `:"code-execution-2025-05-22"` - - - `:"extended-cache-ttl-2025-04-11"` - - - `:"context-1m-2025-08-07"` - - - `:"context-management-2025-06-27"` - - - `:"model-context-window-exceeded-2025-08-26"` - - - `:"skills-2025-10-02"` - - - `:"fast-mode-2026-02-01"` - - - `:"output-300k-2026-03-24"` - - - `:"user-profiles-2026-03-24"` - -### Returns - -- `class BetaUserProfile` - - - `id: String` - - - `created_at: Time` - - A timestamp in RFC 3339 format - - - `metadata: Hash[Symbol, String]` - - - `trust_grants: Hash[Symbol, BetaUserProfileTrustGrant]` - - - `status: String` - - - `type: String` - - - `updated_at: Time` - - A timestamp in RFC 3339 format - - - `external_id: String` - -### Example - -```ruby -require "anthropic" - -anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") - -beta_user_profile = anthropic.beta.user_profiles.create - -puts(beta_user_profile) -``` - -## List - -`beta.user_profiles.list(**kwargs) -> PageCursorV2` - -**get** `/v1/user_profiles` - -List User Profiles - -### Parameters - -- `limit: Integer` - - Query parameter for limit - -- `order: :asc | :desc` - - Query parameter for order - - - `:asc` - - - `:desc` - -- `page: String` - - Query parameter for page - -- `betas: Array[AnthropicBeta]` - - Optional header to specify the beta version(s) you want to use. - - - `String` - - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` - - - `:"message-batches-2024-09-24"` - - - `:"prompt-caching-2024-07-31"` - - - `:"computer-use-2024-10-22"` - - - `:"computer-use-2025-01-24"` - - - `:"pdfs-2024-09-25"` - - - `:"token-counting-2024-11-01"` - - - `:"token-efficient-tools-2025-02-19"` - - - `:"output-128k-2025-02-19"` - - - `:"files-api-2025-04-14"` - - - `:"mcp-client-2025-04-04"` - - - `:"mcp-client-2025-11-20"` - - - `:"dev-full-thinking-2025-05-14"` - - - `:"interleaved-thinking-2025-05-14"` - - - `:"code-execution-2025-05-22"` - - - `:"extended-cache-ttl-2025-04-11"` - - - `:"context-1m-2025-08-07"` - - - `:"context-management-2025-06-27"` - - - `:"model-context-window-exceeded-2025-08-26"` - - - `:"skills-2025-10-02"` - - - `:"fast-mode-2026-02-01"` - - - `:"output-300k-2026-03-24"` - - - `:"user-profiles-2026-03-24"` - -### Returns - -- `class BetaUserProfile` - - - `id: String` - - - `created_at: Time` - - A timestamp in RFC 3339 format - - - `metadata: Hash[Symbol, String]` - - - `trust_grants: Hash[Symbol, BetaUserProfileTrustGrant]` - - - `status: String` - - - `type: String` - - - `updated_at: Time` - - A timestamp in RFC 3339 format - - - `external_id: String` - -### Example - -```ruby -require "anthropic" - -anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") - -page = anthropic.beta.user_profiles.list - -puts(page) -``` - -## Retrieve - -`beta.user_profiles.retrieve(id, **kwargs) -> BetaUserProfile` - -**get** `/v1/user_profiles/{id}` - -Get User Profile - -### Parameters - -- `id: String` - -- `betas: Array[AnthropicBeta]` - - Optional header to specify the beta version(s) you want to use. - - - `String` - - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` - - - `:"message-batches-2024-09-24"` - - - `:"prompt-caching-2024-07-31"` - - - `:"computer-use-2024-10-22"` - - - `:"computer-use-2025-01-24"` - - - `:"pdfs-2024-09-25"` - - - `:"token-counting-2024-11-01"` - - - `:"token-efficient-tools-2025-02-19"` - - - `:"output-128k-2025-02-19"` - - - `:"files-api-2025-04-14"` - - - `:"mcp-client-2025-04-04"` - - - `:"mcp-client-2025-11-20"` - - - `:"dev-full-thinking-2025-05-14"` - - - `:"interleaved-thinking-2025-05-14"` - - - `:"code-execution-2025-05-22"` - - - `:"extended-cache-ttl-2025-04-11"` - - - `:"context-1m-2025-08-07"` - - - `:"context-management-2025-06-27"` - - - `:"model-context-window-exceeded-2025-08-26"` - - - `:"skills-2025-10-02"` - - - `:"fast-mode-2026-02-01"` - - - `:"output-300k-2026-03-24"` - - - `:"user-profiles-2026-03-24"` - -### Returns - -- `class BetaUserProfile` - - - `id: String` - - - `created_at: Time` - - A timestamp in RFC 3339 format - - - `metadata: Hash[Symbol, String]` - - - `trust_grants: Hash[Symbol, BetaUserProfileTrustGrant]` - - - `status: String` - - - `type: String` - - - `updated_at: Time` - - A timestamp in RFC 3339 format - - - `external_id: String` - -### Example - -```ruby -require "anthropic" - -anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") - -beta_user_profile = anthropic.beta.user_profiles.retrieve("id") - -puts(beta_user_profile) -``` - -## Update - -`beta.user_profiles.update(id, **kwargs) -> BetaUserProfile` - -**post** `/v1/user_profiles/{id}` - -Update User Profile - -### Parameters - -- `id: String` - -- `external_id: String` - -- `metadata: Hash[Symbol, String]` - - Key-value pairs to merge into the stored metadata. Keys provided overwrite existing values. To remove a key, set its value to an empty string. Keys not provided are left unchanged. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. - -- `betas: Array[AnthropicBeta]` - - Optional header to specify the beta version(s) you want to use. - - - `String` - - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` - - - `:"message-batches-2024-09-24"` - - - `:"prompt-caching-2024-07-31"` - - - `:"computer-use-2024-10-22"` - - - `:"computer-use-2025-01-24"` - - - `:"pdfs-2024-09-25"` - - - `:"token-counting-2024-11-01"` - - - `:"token-efficient-tools-2025-02-19"` - - - `:"output-128k-2025-02-19"` - - - `:"files-api-2025-04-14"` - - - `:"mcp-client-2025-04-04"` - - - `:"mcp-client-2025-11-20"` - - - `:"dev-full-thinking-2025-05-14"` - - - `:"interleaved-thinking-2025-05-14"` - - - `:"code-execution-2025-05-22"` - - - `:"extended-cache-ttl-2025-04-11"` - - - `:"context-1m-2025-08-07"` - - - `:"context-management-2025-06-27"` - - - `:"model-context-window-exceeded-2025-08-26"` - - - `:"skills-2025-10-02"` - - - `:"fast-mode-2026-02-01"` - - - `:"output-300k-2026-03-24"` - - - `:"user-profiles-2026-03-24"` - -### Returns - -- `class BetaUserProfile` - - - `id: String` - - - `created_at: Time` - - A timestamp in RFC 3339 format - - - `metadata: Hash[Symbol, String]` - - - `trust_grants: Hash[Symbol, BetaUserProfileTrustGrant]` - - - `status: String` - - - `type: String` - - - `updated_at: Time` - - A timestamp in RFC 3339 format - - - `external_id: String` - -### Example - -```ruby -require "anthropic" - -anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") - -beta_user_profile = anthropic.beta.user_profiles.update("id") - -puts(beta_user_profile) -``` - -## Create Enrollment URL - -`beta.user_profiles.create_enrollment_url(id, **kwargs) -> BetaUserProfileEnrollmentURL` - -**post** `/v1/user_profiles/{id}/enrollment_url` - -Create Enrollment URL - -### Parameters - -- `id: String` - -- `betas: Array[AnthropicBeta]` - - Optional header to specify the beta version(s) you want to use. - - - `String` - - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` - - - `:"message-batches-2024-09-24"` - - - `:"prompt-caching-2024-07-31"` - - - `:"computer-use-2024-10-22"` - - - `:"computer-use-2025-01-24"` - - - `:"pdfs-2024-09-25"` - - - `:"token-counting-2024-11-01"` - - - `:"token-efficient-tools-2025-02-19"` - - - `:"output-128k-2025-02-19"` - - - `:"files-api-2025-04-14"` - - - `:"mcp-client-2025-04-04"` - - - `:"mcp-client-2025-11-20"` - - - `:"dev-full-thinking-2025-05-14"` - - - `:"interleaved-thinking-2025-05-14"` - - - `:"code-execution-2025-05-22"` - - - `:"extended-cache-ttl-2025-04-11"` - - - `:"context-1m-2025-08-07"` - - - `:"context-management-2025-06-27"` - - - `:"model-context-window-exceeded-2025-08-26"` - - - `:"skills-2025-10-02"` - - - `:"fast-mode-2026-02-01"` - - - `:"output-300k-2026-03-24"` - - - `:"user-profiles-2026-03-24"` - -### Returns - -- `class BetaUserProfileEnrollmentURL` - - - `expires_at: Time` - - A timestamp in RFC 3339 format - - - `type: String` - - - `url: String` - -### Example - -```ruby -require "anthropic" - -anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") - -beta_user_profile_enrollment_url = anthropic.beta.user_profiles.create_enrollment_url("id") - -puts(beta_user_profile_enrollment_url) -``` - -## Domain Types - -### Beta User Profile - -- `class BetaUserProfile` - - - `id: String` - - - `created_at: Time` - - A timestamp in RFC 3339 format - - - `metadata: Hash[Symbol, String]` - - - `trust_grants: Hash[Symbol, BetaUserProfileTrustGrant]` - - - `status: String` - - - `type: String` - - - `updated_at: Time` - - A timestamp in RFC 3339 format - - - `external_id: String` - -### Beta User Profile Enrollment URL - -- `class BetaUserProfileEnrollmentURL` - - - `expires_at: Time` - - A timestamp in RFC 3339 format - - - `type: String` - - - `url: String` - -### Beta User Profile Trust Grant - -- `class BetaUserProfileTrustGrant` - - - `status: String` diff --git a/content/en/api/ruby/beta/agents.md b/content/en/api/ruby/beta/agents.md new file mode 100644 index 000000000..a7759e25a --- /dev/null +++ b/content/en/api/ruby/beta/agents.md @@ -0,0 +1,4295 @@ +# Agents + +## Create + +`beta.agents.create(**kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `BetaManagedAgentsModel = :"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more | String` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `class BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + +- `name: String` + + Human-readable name for the agent. 1-256 characters. + +- `description: String` + + Description of what the agent does. Up to 2048 characters. + +- `mcp_servers: Array[BetaManagedAgentsURLMCPServerParams]` + + MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `name: String` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: :url` + + - `:url` + + - `url: String` + + Endpoint URL for the MCP server. + +- `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + +- `skills: Array[BetaManagedAgentsSkillParams]` + + Skills available to the agent. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: String` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: String` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: :custom` + + - `:custom` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + +- `system_: String` + + System prompt for the agent. Up to 100,000 characters. + +- `tools: Array[BetaManagedAgentsAgentToolset20260401Params | BetaManagedAgentsMCPToolsetParams | BetaManagedAgentsCustomToolParams]` + + Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfigParams]` + + Per-tool configuration overrides. + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `enabled: bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `class BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: String` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfigParams]` + + Per-tool configuration overrides. + + - `name: String` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `class BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: String` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: :custom` + + - `:custom` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_agent = anthropic.beta.agents.create(model: :"claude-sonnet-4-6", name: "My First Agent") + +puts(beta_managed_agents_agent) +``` + +## List + +`beta.agents.list(**kwargs) -> PageCursor` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `created_at_gte: Time` + + Return agents created at or after this time (inclusive). + +- `created_at_lte: Time` + + Return agents created at or before this time (inclusive). + +- `include_archived: bool` + + Include archived agents in results. Defaults to false. + +- `limit: Integer` + + Maximum results per page. Default 20, maximum 100. + +- `page: String` + + Opaque pagination cursor from a previous response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.agents.list + +puts(page) +``` + +## Retrieve + +`beta.agents.retrieve(agent_id, **kwargs) -> BetaManagedAgentsAgent` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `agent_id: String` + +- `version: Integer` + + Agent version. Omit for the most recent version. Must be at least 1 if specified. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_agent = anthropic.beta.agents.retrieve("agent_011CZkYpogX7uDKUyvBTophP") + +puts(beta_managed_agents_agent) +``` + +## Update + +`beta.agents.update(agent_id, **kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `agent_id: String` + +- `version: Integer` + + The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + +- `description: String` + + Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + +- `mcp_servers: Array[BetaManagedAgentsURLMCPServerParams]` + + MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `name: String` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: :url` + + - `:url` + + - `url: String` + + Endpoint URL for the MCP server. + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + +- `model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `BetaManagedAgentsModel = :"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more | String` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `class BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + +- `name: String` + + Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + +- `skills: Array[BetaManagedAgentsSkillParams]` + + Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: String` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: String` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: :custom` + + - `:custom` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + +- `system_: String` + + System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + +- `tools: Array[BetaManagedAgentsAgentToolset20260401Params | BetaManagedAgentsMCPToolsetParams | BetaManagedAgentsCustomToolParams]` + + Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfigParams]` + + Per-tool configuration overrides. + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `enabled: bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `class BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: String` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfigParams]` + + Per-tool configuration overrides. + + - `name: String` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `class BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: String` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: :custom` + + - `:custom` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_agent = anthropic.beta.agents.update("agent_011CZkYpogX7uDKUyvBTophP", version: 1) + +puts(beta_managed_agents_agent) +``` + +## Archive + +`beta.agents.archive(agent_id, **kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `agent_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_agent = anthropic.beta.agents.archive("agent_011CZkYpogX7uDKUyvBTophP") + +puts(beta_managed_agents_agent) +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `class BetaManagedAgentsAgentToolConfig` + + Configuration for a specific agent tool. + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Agent Tool Config Params + +- `class BetaManagedAgentsAgentToolConfigParams` + + Configuration override for a specific tool within a toolset. + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `enabled: bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Agent Toolset Default Config + +- `class BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `class BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Agent Toolset20260401 + +- `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `class BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfigParams]` + + Per-tool configuration overrides. + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `enabled: bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Always Allow Policy + +- `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + +### Beta Managed Agents Always Ask Policy + +- `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Anthropic Skill + +- `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + +### Beta Managed Agents Anthropic Skill Params + +- `class BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: String` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + +### Beta Managed Agents Custom Skill Params + +- `class BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: String` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: :custom` + + - `:custom` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + +### Beta Managed Agents Custom Tool Input Schema + +- `class BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + +### Beta Managed Agents Custom Tool Params + +- `class BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: String` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: :custom` + + - `:custom` + +### Beta Managed Agents MCP Server URL Definition + +- `class BetaManagedAgentsMCPServerURLDefinition` + + URL-based MCP server connection as returned in API responses. + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + +### Beta Managed Agents MCP Tool Config + +- `class BetaManagedAgentsMCPToolConfig` + + Resolved configuration for a specific MCP tool. + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents MCP Tool Config Params + +- `class BetaManagedAgentsMCPToolConfigParams` + + Configuration override for a specific MCP tool. + + - `name: String` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents MCP Toolset + +- `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + +### Beta Managed Agents MCP Toolset Default Config + +- `class BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `class BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents MCP Toolset Params + +- `class BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: String` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfigParams]` + + Per-tool configuration overrides. + + - `name: String` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + +### Beta Managed Agents Model + +- `BetaManagedAgentsModel = :"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more | String` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + +### Beta Managed Agents Model Config + +- `class BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + +### Beta Managed Agents Model Config Params + +- `class BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + +### Beta Managed Agents Skill Params + +- `BetaManagedAgentsSkillParams = BetaManagedAgentsAnthropicSkillParams | BetaManagedAgentsCustomSkillParams` + + Skill to load in the session container. + + - `class BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: String` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: String` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: :custom` + + - `:custom` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `class BetaManagedAgentsURLMCPServerParams` + + URL-based MCP server connection. + + - `name: String` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: :url` + + - `:url` + + - `url: String` + + Endpoint URL for the MCP server. + +# Versions + +## List + +`beta.agents.versions.list(agent_id, **kwargs) -> PageCursor` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agent_id: String` + +- `limit: Integer` + + Maximum results per page. Default 20, maximum 100. + +- `page: String` + + Opaque pagination cursor. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.agents.versions.list("agent_011CZkYpogX7uDKUyvBTophP") + +puts(page) +``` diff --git a/content/en/api/ruby/beta/agents/archive.md b/content/en/api/ruby/beta/agents/archive.md new file mode 100644 index 000000000..059bff2f1 --- /dev/null +++ b/content/en/api/ruby/beta/agents/archive.md @@ -0,0 +1,371 @@ +## Archive + +`beta.agents.archive(agent_id, **kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `agent_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_agent = anthropic.beta.agents.archive("agent_011CZkYpogX7uDKUyvBTophP") + +puts(beta_managed_agents_agent) +``` diff --git a/content/en/api/ruby/beta/agents/create.md b/content/en/api/ruby/beta/agents/create.md new file mode 100644 index 000000000..1083036f4 --- /dev/null +++ b/content/en/api/ruby/beta/agents/create.md @@ -0,0 +1,739 @@ +## Create + +`beta.agents.create(**kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `BetaManagedAgentsModel = :"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more | String` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `class BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + +- `name: String` + + Human-readable name for the agent. 1-256 characters. + +- `description: String` + + Description of what the agent does. Up to 2048 characters. + +- `mcp_servers: Array[BetaManagedAgentsURLMCPServerParams]` + + MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `name: String` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: :url` + + - `:url` + + - `url: String` + + Endpoint URL for the MCP server. + +- `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + +- `skills: Array[BetaManagedAgentsSkillParams]` + + Skills available to the agent. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: String` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: String` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: :custom` + + - `:custom` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + +- `system_: String` + + System prompt for the agent. Up to 100,000 characters. + +- `tools: Array[BetaManagedAgentsAgentToolset20260401Params | BetaManagedAgentsMCPToolsetParams | BetaManagedAgentsCustomToolParams]` + + Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfigParams]` + + Per-tool configuration overrides. + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `enabled: bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `class BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: String` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfigParams]` + + Per-tool configuration overrides. + + - `name: String` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `class BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: String` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: :custom` + + - `:custom` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_agent = anthropic.beta.agents.create(model: :"claude-sonnet-4-6", name: "My First Agent") + +puts(beta_managed_agents_agent) +``` diff --git a/content/en/api/ruby/beta/agents/list.md b/content/en/api/ruby/beta/agents/list.md new file mode 100644 index 000000000..86445baf1 --- /dev/null +++ b/content/en/api/ruby/beta/agents/list.md @@ -0,0 +1,389 @@ +## List + +`beta.agents.list(**kwargs) -> PageCursor` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `created_at_gte: Time` + + Return agents created at or after this time (inclusive). + +- `created_at_lte: Time` + + Return agents created at or before this time (inclusive). + +- `include_archived: bool` + + Include archived agents in results. Defaults to false. + +- `limit: Integer` + + Maximum results per page. Default 20, maximum 100. + +- `page: String` + + Opaque pagination cursor from a previous response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.agents.list + +puts(page) +``` diff --git a/content/en/api/ruby/beta/agents/retrieve.md b/content/en/api/ruby/beta/agents/retrieve.md new file mode 100644 index 000000000..0a8ba7d5d --- /dev/null +++ b/content/en/api/ruby/beta/agents/retrieve.md @@ -0,0 +1,375 @@ +## Retrieve + +`beta.agents.retrieve(agent_id, **kwargs) -> BetaManagedAgentsAgent` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `agent_id: String` + +- `version: Integer` + + Agent version. Omit for the most recent version. Must be at least 1 if specified. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_agent = anthropic.beta.agents.retrieve("agent_011CZkYpogX7uDKUyvBTophP") + +puts(beta_managed_agents_agent) +``` diff --git a/content/en/api/ruby/beta/agents/update.md b/content/en/api/ruby/beta/agents/update.md new file mode 100644 index 000000000..b1caf57be --- /dev/null +++ b/content/en/api/ruby/beta/agents/update.md @@ -0,0 +1,745 @@ +## Update + +`beta.agents.update(agent_id, **kwargs) -> BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `agent_id: String` + +- `version: Integer` + + The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + +- `description: String` + + Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + +- `mcp_servers: Array[BetaManagedAgentsURLMCPServerParams]` + + MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `name: String` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: :url` + + - `:url` + + - `url: String` + + Endpoint URL for the MCP server. + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + +- `model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` + + Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `BetaManagedAgentsModel = :"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more | String` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `class BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + +- `name: String` + + Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + +- `skills: Array[BetaManagedAgentsSkillParams]` + + Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `class BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: String` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + + - `class BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: String` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: :custom` + + - `:custom` + + - `version: String` + + Version to pin. Defaults to latest if omitted. + +- `system_: String` + + System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + +- `tools: Array[BetaManagedAgentsAgentToolset20260401Params | BetaManagedAgentsMCPToolsetParams | BetaManagedAgentsCustomToolParams]` + + Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `class BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfigParams]` + + Per-tool configuration overrides. + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `enabled: bool` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled: bool` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `class BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: String` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfigParams]` + + Per-tool configuration overrides. + + - `name: String` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled: bool` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled: bool` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `class BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: String` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: :custom` + + - `:custom` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_agent = anthropic.beta.agents.update("agent_011CZkYpogX7uDKUyvBTophP", version: 1) + +puts(beta_managed_agents_agent) +``` diff --git a/content/en/api/ruby/beta/agents/versions.md b/content/en/api/ruby/beta/agents/versions.md new file mode 100644 index 000000000..72258b6f2 --- /dev/null +++ b/content/en/api/ruby/beta/agents/versions.md @@ -0,0 +1,381 @@ +# Versions + +## List + +`beta.agents.versions.list(agent_id, **kwargs) -> PageCursor` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agent_id: String` + +- `limit: Integer` + + Maximum results per page. Default 20, maximum 100. + +- `page: String` + + Opaque pagination cursor. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.agents.versions.list("agent_011CZkYpogX7uDKUyvBTophP") + +puts(page) +``` diff --git a/content/en/api/ruby/beta/agents/versions/list.md b/content/en/api/ruby/beta/agents/versions/list.md new file mode 100644 index 000000000..33842392c --- /dev/null +++ b/content/en/api/ruby/beta/agents/versions/list.md @@ -0,0 +1,379 @@ +## List + +`beta.agents.versions.list(agent_id, **kwargs) -> PageCursor` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agent_id: String` + +- `limit: Integer` + + Maximum results per page. Default 20, maximum 100. + +- `page: String` + + Opaque pagination cursor. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: String` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `metadata: Hash[Symbol, String]` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `version: Integer` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.agents.versions.list("agent_011CZkYpogX7uDKUyvBTophP") + +puts(page) +``` diff --git a/content/en/api/ruby/beta/environments.md b/content/en/api/ruby/beta/environments.md new file mode 100644 index 000000000..13ef14626 --- /dev/null +++ b/content/en/api/ruby/beta/environments.md @@ -0,0 +1,1716 @@ +# Environments + +## Create + +`beta.environments.create(**kwargs) -> BetaEnvironment` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `name: String` + + Human-readable name for the environment + +- `config: BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `packages: BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + +- `description: String` + + Optional description of the environment + +- `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment = anthropic.beta.environments.create(name: "python-data-analysis") + +puts(beta_environment) +``` + +## List + +`beta.environments.list(**kwargs) -> PageCursor` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `include_archived: bool` + + Include archived environments in the response + +- `limit: Integer` + + Maximum number of environments to return + +- `page: String` + + Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.environments.list + +puts(page) +``` + +## Retrieve + +`beta.environments.retrieve(environment_id, **kwargs) -> BetaEnvironment` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `environment_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment = anthropic.beta.environments.retrieve("env_011CZkZ9X2dpNyB7HsEFoRfW") + +puts(beta_environment) +``` + +## Update + +`beta.environments.update(environment_id, **kwargs) -> BetaEnvironment` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `environment_id: String` + +- `config: BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `packages: BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + +- `description: String` + + Updated description of the environment + +- `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + +- `name: String` + + Updated name for the environment + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment = anthropic.beta.environments.update("env_011CZkZ9X2dpNyB7HsEFoRfW") + +puts(beta_environment) +``` + +## Delete + +`beta.environments.delete(environment_id, **kwargs) -> BetaEnvironmentDeleteResponse` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `environment_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironmentDeleteResponse` + + Response after deleting an environment. + + - `id: String` + + Environment identifier + + - `type: :environment_deleted` + + The type of response + + - `:environment_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment_delete_response = anthropic.beta.environments.delete("env_011CZkZ9X2dpNyB7HsEFoRfW") + +puts(beta_environment_delete_response) +``` + +## Archive + +`beta.environments.archive(environment_id, **kwargs) -> BetaEnvironment` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `environment_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment = anthropic.beta.environments.archive("env_011CZkZ9X2dpNyB7HsEFoRfW") + +puts(beta_environment) +``` + +## Domain Types + +### Beta Cloud Config + +- `class BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + +### Beta Cloud Config Params + +- `class BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `packages: BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + +### Beta Environment + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `class BetaEnvironmentDeleteResponse` + + Response after deleting an environment. + + - `id: String` + + Environment identifier + + - `type: :environment_deleted` + + The type of response + + - `:environment_deleted` + +### Beta Limited Network + +- `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + +### Beta Limited Network Params + +- `class BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + +### Beta Packages + +- `class BetaPackages` + + Packages (and their versions) available in this environment. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + +### Beta Packages Params + +- `class BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + +### Beta Unrestricted Network + +- `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` diff --git a/content/en/api/ruby/beta/environments/archive.md b/content/en/api/ruby/beta/environments/archive.md new file mode 100644 index 000000000..b3698aebe --- /dev/null +++ b/content/en/api/ruby/beta/environments/archive.md @@ -0,0 +1,193 @@ +## Archive + +`beta.environments.archive(environment_id, **kwargs) -> BetaEnvironment` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `environment_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment = anthropic.beta.environments.archive("env_011CZkZ9X2dpNyB7HsEFoRfW") + +puts(beta_environment) +``` diff --git a/content/en/api/ruby/beta/environments/create.md b/content/en/api/ruby/beta/environments/create.md new file mode 100644 index 000000000..7fbd1d1fa --- /dev/null +++ b/content/en/api/ruby/beta/environments/create.md @@ -0,0 +1,291 @@ +## Create + +`beta.environments.create(**kwargs) -> BetaEnvironment` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `name: String` + + Human-readable name for the environment + +- `config: BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `packages: BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + +- `description: String` + + Optional description of the environment + +- `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment = anthropic.beta.environments.create(name: "python-data-analysis") + +puts(beta_environment) +``` diff --git a/content/en/api/ruby/beta/environments/delete.md b/content/en/api/ruby/beta/environments/delete.md new file mode 100644 index 000000000..dbb70ec91 --- /dev/null +++ b/content/en/api/ruby/beta/environments/delete.md @@ -0,0 +1,89 @@ +## Delete + +`beta.environments.delete(environment_id, **kwargs) -> BetaEnvironmentDeleteResponse` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `environment_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironmentDeleteResponse` + + Response after deleting an environment. + + - `id: String` + + Environment identifier + + - `type: :environment_deleted` + + The type of response + + - `:environment_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment_delete_response = anthropic.beta.environments.delete("env_011CZkZ9X2dpNyB7HsEFoRfW") + +puts(beta_environment_delete_response) +``` diff --git a/content/en/api/ruby/beta/environments/list.md b/content/en/api/ruby/beta/environments/list.md new file mode 100644 index 000000000..9705e8e60 --- /dev/null +++ b/content/en/api/ruby/beta/environments/list.md @@ -0,0 +1,203 @@ +## List + +`beta.environments.list(**kwargs) -> PageCursor` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `include_archived: bool` + + Include archived environments in the response + +- `limit: Integer` + + Maximum number of environments to return + +- `page: String` + + Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.environments.list + +puts(page) +``` diff --git a/content/en/api/ruby/beta/environments/retrieve.md b/content/en/api/ruby/beta/environments/retrieve.md new file mode 100644 index 000000000..5f5346135 --- /dev/null +++ b/content/en/api/ruby/beta/environments/retrieve.md @@ -0,0 +1,193 @@ +## Retrieve + +`beta.environments.retrieve(environment_id, **kwargs) -> BetaEnvironment` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `environment_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment = anthropic.beta.environments.retrieve("env_011CZkZ9X2dpNyB7HsEFoRfW") + +puts(beta_environment) +``` diff --git a/content/en/api/ruby/beta/environments/update.md b/content/en/api/ruby/beta/environments/update.md new file mode 100644 index 000000000..a653ebab5 --- /dev/null +++ b/content/en/api/ruby/beta/environments/update.md @@ -0,0 +1,293 @@ +## Update + +`beta.environments.update(environment_id, **kwargs) -> BetaEnvironment` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `environment_id: String` + +- `config: BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetworkParams` + + Network configuration policy. Omit on update to preserve the existing value. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `packages: BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + +- `description: String` + + Updated description of the environment + +- `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + +- `name: String` + + Updated name for the environment + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: String` + + Environment identifier (e.g., 'env_...') + + - `archived_at: String` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `class BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: :unrestricted` + + Network policy type + + - `:unrestricted` + + - `class BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: bool` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: bool` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array[String]` + + Specifies domains the container can reach. + + - `type: :limited` + + Network policy type + + - `:limited` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array[String]` + + Ubuntu/Debian packages to install + + - `cargo: Array[String]` + + Rust packages to install + + - `gem_: Array[String]` + + Ruby packages to install + + - `go: Array[String]` + + Go packages to install + + - `npm: Array[String]` + + Node.js packages to install + + - `pip: Array[String]` + + Python packages to install + + - `type: :packages` + + Package configuration type + + - `:packages` + + - `type: :cloud` + + Environment type + + - `:cloud` + + - `created_at: String` + + RFC 3339 timestamp when environment was created + + - `description: String` + + User-provided description for the environment + + - `metadata: Hash[Symbol, String]` + + User-provided metadata key-value pairs + + - `name: String` + + Human-readable name for the environment + + - `type: :environment` + + The type of object (always 'environment') + + - `:environment` + + - `updated_at: String` + + RFC 3339 timestamp when environment was last updated + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_environment = anthropic.beta.environments.update("env_011CZkZ9X2dpNyB7HsEFoRfW") + +puts(beta_environment) +``` diff --git a/content/en/api/ruby/beta/files.md b/content/en/api/ruby/beta/files.md index 8b751e627..b43a1e602 100644 --- a/content/en/api/ruby/beta/files.md +++ b/content/en/api/ruby/beta/files.md @@ -20,7 +20,7 @@ Upload File - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Upload File - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata` @@ -104,6 +102,20 @@ Upload File Whether the file can be downloaded. + - `scope: BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` + ### Example ```ruby @@ -140,13 +152,17 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. +- `scope_id: String` + + Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `betas: Array[AnthropicBeta]` Optional header to specify the beta version(s) you want to use. - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -190,8 +206,6 @@ List Files - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata` @@ -230,6 +244,20 @@ List Files Whether the file can be downloaded. + - `scope: BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` + ### Example ```ruby @@ -262,7 +290,7 @@ Download File - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -306,8 +334,6 @@ Download File - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `StringIO` @@ -344,7 +370,7 @@ Get File Metadata - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -388,8 +414,6 @@ Get File Metadata - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata` @@ -428,6 +452,20 @@ Get File Metadata Whether the file can be downloaded. + - `scope: BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` + ### Example ```ruby @@ -460,7 +498,7 @@ Delete File - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -504,8 +542,6 @@ Delete File - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class DeletedFile` @@ -536,6 +572,20 @@ puts(deleted_file) ## Domain Types +### Beta File Scope + +- `class BetaFileScope` + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` + ### Deleted File - `class DeletedFile` @@ -589,3 +639,17 @@ puts(deleted_file) - `downloadable: bool` Whether the file can be downloaded. + + - `scope: BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` diff --git a/content/en/api/ruby/beta/files/delete.md b/content/en/api/ruby/beta/files/delete.md index 281c0fbbf..8d953d26f 100644 --- a/content/en/api/ruby/beta/files/delete.md +++ b/content/en/api/ruby/beta/files/delete.md @@ -18,7 +18,7 @@ Delete File - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Delete File - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class DeletedFile` diff --git a/content/en/api/ruby/beta/files/download.md b/content/en/api/ruby/beta/files/download.md index 7efe80b36..222f04107 100644 --- a/content/en/api/ruby/beta/files/download.md +++ b/content/en/api/ruby/beta/files/download.md @@ -18,7 +18,7 @@ Download File - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Download File - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `StringIO` diff --git a/content/en/api/ruby/beta/files/list.md b/content/en/api/ruby/beta/files/list.md index 2c9c8ba39..78a816c8c 100644 --- a/content/en/api/ruby/beta/files/list.md +++ b/content/en/api/ruby/beta/files/list.md @@ -22,13 +22,17 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. +- `scope_id: String` + + Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `betas: Array[AnthropicBeta]` Optional header to specify the beta version(s) you want to use. - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -72,8 +76,6 @@ List Files - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata` @@ -112,6 +114,20 @@ List Files Whether the file can be downloaded. + - `scope: BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` + ### Example ```ruby diff --git a/content/en/api/ruby/beta/files/retrieve_metadata.md b/content/en/api/ruby/beta/files/retrieve_metadata.md index 618a26389..75a2779dd 100644 --- a/content/en/api/ruby/beta/files/retrieve_metadata.md +++ b/content/en/api/ruby/beta/files/retrieve_metadata.md @@ -18,7 +18,7 @@ Get File Metadata - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Get File Metadata - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata` @@ -102,6 +100,20 @@ Get File Metadata Whether the file can be downloaded. + - `scope: BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` + ### Example ```ruby diff --git a/content/en/api/ruby/beta/files/upload.md b/content/en/api/ruby/beta/files/upload.md index 079d7bb4e..51d5ae427 100644 --- a/content/en/api/ruby/beta/files/upload.md +++ b/content/en/api/ruby/beta/files/upload.md @@ -18,7 +18,7 @@ Upload File - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -62,8 +62,6 @@ Upload File - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class FileMetadata` @@ -102,6 +100,20 @@ Upload File Whether the file can be downloaded. + - `scope: BetaFileScope` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: String` + + The ID of the scoping resource (e.g., the session ID). + + - `type: :session` + + The type of scope (e.g., `"session"`). + + - `:session` + ### Example ```ruby diff --git a/content/en/api/ruby/beta/messages.md b/content/en/api/ruby/beta/messages.md index f3ce60fc3..6b13f4e59 100644 --- a/content/en/api/ruby/beta/messages.md +++ b/content/en/api/ruby/beta/messages.md @@ -2599,15 +2599,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -4676,17 +4680,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. -- `user_profile_id: String` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Array[AnthropicBeta]` Optional header to specify the beta version(s) you want to use. - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -4730,8 +4730,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessage` @@ -5655,15 +5653,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -8567,15 +8569,19 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -10554,7 +10560,7 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -10598,8 +10604,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageTokensCount` @@ -10625,7 +10629,7 @@ anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") beta_message_tokens_count = anthropic.beta.messages.count_tokens( messages: [{content: "string", role: :user}], - model: :"claude-opus-4-6" + model: :"claude-mythos-preview" ) puts(beta_message_tokens_count) @@ -17816,15 +17820,19 @@ puts(beta_message_tokens_count) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -23160,15 +23168,19 @@ puts(beta_message_tokens_count) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -24404,15 +24416,19 @@ puts(beta_message_tokens_count) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -32953,7 +32969,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Must be unique for each request within the Message Batch. - - `params: { max_tokens, messages, model, 20 more}` + - `params: { max_tokens, messages, model, 19 more}` Messages API creation parameters for the individual request. @@ -35544,15 +35560,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -37621,17 +37641,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id: String` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Array[AnthropicBeta]` Optional header to specify the beta version(s) you want to use. - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -37675,8 +37691,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` @@ -37808,7 +37822,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -37852,8 +37866,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` @@ -37988,7 +38000,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -38032,8 +38044,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` @@ -38160,7 +38170,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -38204,8 +38214,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` @@ -38332,7 +38340,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -38376,8 +38384,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaDeletedMessageBatch` @@ -38430,7 +38436,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -38474,8 +38480,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatchIndividualResponse` @@ -39417,15 +39421,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -40993,15 +41001,19 @@ puts(beta_message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -42365,15 +42377,19 @@ puts(beta_message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -43699,15 +43715,19 @@ puts(beta_message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` diff --git a/content/en/api/ruby/beta/messages/batches.md b/content/en/api/ruby/beta/messages/batches.md index 278425dff..d641a4e5a 100644 --- a/content/en/api/ruby/beta/messages/batches.md +++ b/content/en/api/ruby/beta/messages/batches.md @@ -24,7 +24,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Must be unique for each request within the Message Batch. - - `params: { max_tokens, messages, model, 20 more}` + - `params: { max_tokens, messages, model, 19 more}` Messages API creation parameters for the individual request. @@ -2615,15 +2615,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -4692,17 +4696,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id: String` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Array[AnthropicBeta]` Optional header to specify the beta version(s) you want to use. - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -4746,8 +4746,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` @@ -4879,7 +4877,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -4923,8 +4921,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` @@ -5059,7 +5055,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -5103,8 +5099,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` @@ -5231,7 +5225,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -5275,8 +5269,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` @@ -5403,7 +5395,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -5447,8 +5439,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaDeletedMessageBatch` @@ -5501,7 +5491,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -5545,8 +5535,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatchIndividualResponse` @@ -6488,15 +6476,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -8064,15 +8056,19 @@ puts(beta_message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -9436,15 +9432,19 @@ puts(beta_message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -10770,15 +10770,19 @@ puts(beta_message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` diff --git a/content/en/api/ruby/beta/messages/batches/cancel.md b/content/en/api/ruby/beta/messages/batches/cancel.md index f85143e38..eee449d0c 100644 --- a/content/en/api/ruby/beta/messages/batches/cancel.md +++ b/content/en/api/ruby/beta/messages/batches/cancel.md @@ -22,7 +22,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` diff --git a/content/en/api/ruby/beta/messages/batches/create.md b/content/en/api/ruby/beta/messages/batches/create.md index 39afce823..bd8ce3afa 100644 --- a/content/en/api/ruby/beta/messages/batches/create.md +++ b/content/en/api/ruby/beta/messages/batches/create.md @@ -22,7 +22,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Must be unique for each request within the Message Batch. - - `params: { max_tokens, messages, model, 20 more}` + - `params: { max_tokens, messages, model, 19 more}` Messages API creation parameters for the individual request. @@ -2613,15 +2613,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -4690,17 +4694,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id: String` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Array[AnthropicBeta]` Optional header to specify the beta version(s) you want to use. - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -4744,8 +4744,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` diff --git a/content/en/api/ruby/beta/messages/batches/delete.md b/content/en/api/ruby/beta/messages/batches/delete.md index 29c339da1..b092bd5e0 100644 --- a/content/en/api/ruby/beta/messages/batches/delete.md +++ b/content/en/api/ruby/beta/messages/batches/delete.md @@ -22,7 +22,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaDeletedMessageBatch` diff --git a/content/en/api/ruby/beta/messages/batches/list.md b/content/en/api/ruby/beta/messages/batches/list.md index 0f82da250..530e84f79 100644 --- a/content/en/api/ruby/beta/messages/batches/list.md +++ b/content/en/api/ruby/beta/messages/batches/list.md @@ -30,7 +30,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` diff --git a/content/en/api/ruby/beta/messages/batches/results.md b/content/en/api/ruby/beta/messages/batches/results.md index 14181f5a3..061c81daa 100644 --- a/content/en/api/ruby/beta/messages/batches/results.md +++ b/content/en/api/ruby/beta/messages/batches/results.md @@ -22,7 +22,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatchIndividualResponse` @@ -1009,15 +1007,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` diff --git a/content/en/api/ruby/beta/messages/batches/retrieve.md b/content/en/api/ruby/beta/messages/batches/retrieve.md index b0f006e5b..67899c044 100644 --- a/content/en/api/ruby/beta/messages/batches/retrieve.md +++ b/content/en/api/ruby/beta/messages/batches/retrieve.md @@ -20,7 +20,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageBatch` diff --git a/content/en/api/ruby/beta/messages/count_tokens.md b/content/en/api/ruby/beta/messages/count_tokens.md index 79a5e2068..3b804ada5 100644 --- a/content/en/api/ruby/beta/messages/count_tokens.md +++ b/content/en/api/ruby/beta/messages/count_tokens.md @@ -2589,15 +2589,19 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -4576,7 +4580,7 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -4620,8 +4624,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessageTokensCount` @@ -4647,7 +4649,7 @@ anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") beta_message_tokens_count = anthropic.beta.messages.count_tokens( messages: [{content: "string", role: :user}], - model: :"claude-opus-4-6" + model: :"claude-mythos-preview" ) puts(beta_message_tokens_count) diff --git a/content/en/api/ruby/beta/messages/create.md b/content/en/api/ruby/beta/messages/create.md index 67c9d0882..8a0f8ebd4 100644 --- a/content/en/api/ruby/beta/messages/create.md +++ b/content/en/api/ruby/beta/messages/create.md @@ -2597,15 +2597,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -4674,17 +4678,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. -- `user_profile_id: String` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas: Array[AnthropicBeta]` Optional header to specify the beta version(s) you want to use. - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -4728,8 +4728,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaMessage` @@ -5653,15 +5651,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` diff --git a/content/en/api/ruby/beta/models.md b/content/en/api/ruby/beta/models.md index e2824d892..52e90b6a8 100644 --- a/content/en/api/ruby/beta/models.md +++ b/content/en/api/ruby/beta/models.md @@ -32,7 +32,7 @@ The Models API response can be used to determine which models are available for - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -76,8 +76,6 @@ The Models API response can be used to determine which models are available for - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaModelInfo` @@ -296,7 +294,7 @@ The Models API response can be used to determine information about a specific mo - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -340,8 +338,6 @@ The Models API response can be used to determine information about a specific mo - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaModelInfo` diff --git a/content/en/api/ruby/beta/models/list.md b/content/en/api/ruby/beta/models/list.md index d5900d3a3..416efbbee 100644 --- a/content/en/api/ruby/beta/models/list.md +++ b/content/en/api/ruby/beta/models/list.md @@ -30,7 +30,7 @@ The Models API response can be used to determine which models are available for - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ The Models API response can be used to determine which models are available for - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaModelInfo` diff --git a/content/en/api/ruby/beta/models/retrieve.md b/content/en/api/ruby/beta/models/retrieve.md index b088b1088..45bb86e90 100644 --- a/content/en/api/ruby/beta/models/retrieve.md +++ b/content/en/api/ruby/beta/models/retrieve.md @@ -20,7 +20,7 @@ The Models API response can be used to determine information about a specific mo - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ The Models API response can be used to determine information about a specific mo - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class BetaModelInfo` diff --git a/content/en/api/ruby/beta/sessions.md b/content/en/api/ruby/beta/sessions.md new file mode 100644 index 000000000..c99e1ed56 --- /dev/null +++ b/content/en/api/ruby/beta/sessions.md @@ -0,0 +1,14215 @@ +# Sessions + +## Create + +`beta.sessions.create(**kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `agent: String | BetaManagedAgentsAgentParams` + + Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `String` + + - `class BetaManagedAgentsAgentParams` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: String` + + The `agent` ID. + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +- `environment_id: String` + + ID of the `environment` defining the container configuration for this session. + +- `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the session. + +- `resources: Array[BetaManagedAgentsGitHubRepositoryResourceParams | BetaManagedAgentsFileResourceParams]` + + Resources (e.g. repositories, files) to mount into the session's container. + + - `class BetaManagedAgentsGitHubRepositoryResourceParams` + + Mount a GitHub repository into the session's container. + + - `authorization_token: String` + + GitHub authorization token used to clone the repository. + + - `type: :github_repository` + + - `:github_repository` + + - `url: String` + + Github URL of the repository + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `mount_path: String` + + Mount path in the container. Defaults to `/workspace/`. + + - `class BetaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `mount_path: String` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `title: String` + + Human-readable session title. + +- `vault_ids: Array[String]` + + Vault IDs for stored credentials the agent can use during the session. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_session = anthropic.beta.sessions.create( + agent: "agent_011CZkYpogX7uDKUyvBTophP", + environment_id: "env_011CZkZ9X2dpNyB7HsEFoRfW" +) + +puts(beta_managed_agents_session) +``` + +## List + +`beta.sessions.list(**kwargs) -> PageCursor` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `agent_id: String` + + Filter sessions created with this agent ID. + +- `agent_version: Integer` + + Filter by agent version. Only applies when agent_id is also set. + +- `created_at_gt: Time` + + Return sessions created after this time (exclusive). + +- `created_at_gte: Time` + + Return sessions created at or after this time (inclusive). + +- `created_at_lt: Time` + + Return sessions created before this time (exclusive). + +- `created_at_lte: Time` + + Return sessions created at or before this time (inclusive). + +- `include_archived: bool` + + When true, includes archived sessions. Default: false (exclude archived). + +- `limit: Integer` + + Maximum number of results to return. + +- `order: :asc | :desc` + + Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `:asc` + + - `:desc` + +- `page: String` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.sessions.list + +puts(page) +``` + +## Retrieve + +`beta.sessions.retrieve(session_id, **kwargs) -> BetaManagedAgentsSession` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_session = anthropic.beta.sessions.retrieve("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_session) +``` + +## Update + +`beta.sessions.update(session_id, **kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `session_id: String` + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + +- `title: String` + + Human-readable session title. + +- `vault_ids: Array[String]` + + Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_session = anthropic.beta.sessions.update("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_session) +``` + +## Delete + +`beta.sessions.delete(session_id, **kwargs) -> BetaManagedAgentsDeletedSession` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedSession` + + Confirmation that a `session` has been permanently deleted. + + - `id: String` + + - `type: :session_deleted` + + - `:session_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_deleted_session = anthropic.beta.sessions.delete("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_deleted_session) +``` + +## Archive + +`beta.sessions.archive(session_id, **kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_session = anthropic.beta.sessions.archive("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_session) +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `class BetaManagedAgentsAgentParams` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: String` + + The `agent` ID. + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + +### Beta Managed Agents Cache Creation Usage + +- `class BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + +### Beta Managed Agents Deleted Session + +- `class BetaManagedAgentsDeletedSession` + + Confirmation that a `session` has been permanently deleted. + + - `id: String` + + - `type: :session_deleted` + + - `:session_deleted` + +### Beta Managed Agents File Resource Params + +- `class BetaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `mount_path: String` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `class BetaManagedAgentsGitHubRepositoryResourceParams` + + Mount a GitHub repository into the session's container. + + - `authorization_token: String` + + GitHub authorization token used to clone the repository. + + - `type: :github_repository` + + - `:github_repository` + + - `url: String` + + Github URL of the repository + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `mount_path: String` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `class BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + +### Beta Managed Agents Session Stats + +- `class BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `class BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + +# Events + +## List + +`beta.sessions.events.list(session_id, **kwargs) -> PageCursor` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `session_id: String` + +- `limit: Integer` + + Query parameter for limit + +- `order: :asc | :desc` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `:asc` + + - `:desc` + +- `page: String` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.sessions.events.list("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(page) +``` + +## Send + +`beta.sessions.events.send_(session_id, **kwargs) -> BetaManagedAgentsSendSessionEvents` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `session_id: String` + +- `events: Array[BetaManagedAgentsEventParams]` + + Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data: Array[BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | BetaManagedAgentsUserCustomToolResultEvent]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_send_session_events = anthropic.beta.sessions.events.send_( + "sesn_011CZkZAtmR3yMPDzynEDxu7", + events: [{content: [{text: "Where is my order #1234?", type: :text}], type: :"user.message"}] +) + +puts(beta_managed_agents_send_session_events) +``` + +## Stream + +`beta.sessions.events.stream(session_id, **kwargs) -> BetaManagedAgentsStreamSessionEvents` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_stream_session_events = anthropic.beta.sessions.events.stream("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_stream_session_events) +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + +### Beta Managed Agents Agent Message Event + +- `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + +### Beta Managed Agents Base64 Document Source + +- `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + +### Beta Managed Agents Base64 Image Source + +- `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + +### Beta Managed Agents Billing Error + +- `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + +### Beta Managed Agents Document Block + +- `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + +### Beta Managed Agents Event Params + +- `BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams | BetaManagedAgentsUserInterruptEventParams | BetaManagedAgentsUserToolConfirmationEventParams | BetaManagedAgentsUserCustomToolResultEventParams` + + Union type for event parameters that can be sent to a session. + + - `class BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + +### Beta Managed Agents File Image Source + +- `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + +### Beta Managed Agents Image Block + +- `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + +### Beta Managed Agents MCP Authentication Failed Error + +- `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + +### Beta Managed Agents MCP Connection Failed Error + +- `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + +### Beta Managed Agents Model Overloaded Error + +- `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + +### Beta Managed Agents Model Rate Limited Error + +- `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + +### Beta Managed Agents Model Request Failed Error + +- `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + +### Beta Managed Agents Plain Text Document Source + +- `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + +### Beta Managed Agents Retry Status Exhausted + +- `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + +### Beta Managed Agents Retry Status Retrying + +- `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + +### Beta Managed Agents Retry Status Terminal + +- `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + +### Beta Managed Agents Send Session Events + +- `class BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data: Array[BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | BetaManagedAgentsUserCustomToolResultEvent]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + +### Beta Managed Agents Session Error Event + +- `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + +### Beta Managed Agents Session Event + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + +### Beta Managed Agents Session Retries Exhausted + +- `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + +### Beta Managed Agents Session Status Idle Event + +- `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `class BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + +### Beta Managed Agents Stream Session Events + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Beta Managed Agents Text Block + +- `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + +### Beta Managed Agents Unknown Error + +- `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + +### Beta Managed Agents URL Document Source + +- `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `class BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `class BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `class BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `class BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`beta.sessions.resources.add(session_id, **kwargs) -> BetaManagedAgentsFileResource` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `session_id: String` + +- `file_id: String` + + ID of a previously uploaded file. + +- `type: :file` + + - `:file` + +- `mount_path: String` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_file_resource = anthropic.beta.sessions.resources.add( + "sesn_011CZkZAtmR3yMPDzynEDxu7", + file_id: "file_011CNha8iCJcU1wXNR6q4V8w", + type: :file +) + +puts(beta_managed_agents_file_resource) +``` + +## List + +`beta.sessions.resources.list(session_id, **kwargs) -> PageCursor` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `session_id: String` + +- `limit: Integer` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `page: String` + + Opaque cursor from a previous response's next_page field. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.sessions.resources.list("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(page) +``` + +## Retrieve + +`beta.sessions.resources.retrieve(resource_id, **kwargs) -> ResourceRetrieveResponse` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `session_id: String` + +- `resource_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +resource = anthropic.beta.sessions.resources.retrieve( + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id: "sesn_011CZkZAtmR3yMPDzynEDxu7" +) + +puts(resource) +``` + +## Update + +`beta.sessions.resources.update(resource_id, **kwargs) -> ResourceUpdateResponse` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `session_id: String` + +- `resource_id: String` + +- `authorization_token: String` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +resource = anthropic.beta.sessions.resources.update( + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id: "sesn_011CZkZAtmR3yMPDzynEDxu7", + authorization_token: "ghp_exampletoken" +) + +puts(resource) +``` + +## Delete + +`beta.sessions.resources.delete(resource_id, **kwargs) -> BetaManagedAgentsDeleteSessionResource` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `session_id: String` + +- `resource_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: String` + + - `type: :session_resource_deleted` + + - `:session_resource_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_delete_session_resource = anthropic.beta.sessions.resources.delete( + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id: "sesn_011CZkZAtmR3yMPDzynEDxu7" +) + +puts(beta_managed_agents_delete_session_resource) +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `class BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: String` + + - `type: :session_resource_deleted` + + - `:session_resource_deleted` + +### Beta Managed Agents File Resource + +- `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + +### Beta Managed Agents Session Resource + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Resource Retrieve Response + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Resource Update Response + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format diff --git a/content/en/api/ruby/beta/sessions/archive.md b/content/en/api/ruby/beta/sessions/archive.md new file mode 100644 index 000000000..81c18e1da --- /dev/null +++ b/content/en/api/ruby/beta/sessions/archive.md @@ -0,0 +1,503 @@ +## Archive + +`beta.sessions.archive(session_id, **kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_session = anthropic.beta.sessions.archive("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_session) +``` diff --git a/content/en/api/ruby/beta/sessions/create.md b/content/en/api/ruby/beta/sessions/create.md new file mode 100644 index 000000000..853e5771d --- /dev/null +++ b/content/en/api/ruby/beta/sessions/create.md @@ -0,0 +1,606 @@ +## Create + +`beta.sessions.create(**kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `agent: String | BetaManagedAgentsAgentParams` + + Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `String` + + - `class BetaManagedAgentsAgentParams` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: String` + + The `agent` ID. + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +- `environment_id: String` + + ID of the `environment` defining the container configuration for this session. + +- `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the session. + +- `resources: Array[BetaManagedAgentsGitHubRepositoryResourceParams | BetaManagedAgentsFileResourceParams]` + + Resources (e.g. repositories, files) to mount into the session's container. + + - `class BetaManagedAgentsGitHubRepositoryResourceParams` + + Mount a GitHub repository into the session's container. + + - `authorization_token: String` + + GitHub authorization token used to clone the repository. + + - `type: :github_repository` + + - `:github_repository` + + - `url: String` + + Github URL of the repository + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `mount_path: String` + + Mount path in the container. Defaults to `/workspace/`. + + - `class BetaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `mount_path: String` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `title: String` + + Human-readable session title. + +- `vault_ids: Array[String]` + + Vault IDs for stored credentials the agent can use during the session. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_session = anthropic.beta.sessions.create( + agent: "agent_011CZkYpogX7uDKUyvBTophP", + environment_id: "env_011CZkZ9X2dpNyB7HsEFoRfW" +) + +puts(beta_managed_agents_session) +``` diff --git a/content/en/api/ruby/beta/sessions/delete.md b/content/en/api/ruby/beta/sessions/delete.md new file mode 100644 index 000000000..f3cd76833 --- /dev/null +++ b/content/en/api/ruby/beta/sessions/delete.md @@ -0,0 +1,85 @@ +## Delete + +`beta.sessions.delete(session_id, **kwargs) -> BetaManagedAgentsDeletedSession` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedSession` + + Confirmation that a `session` has been permanently deleted. + + - `id: String` + + - `type: :session_deleted` + + - `:session_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_deleted_session = anthropic.beta.sessions.delete("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_deleted_session) +``` diff --git a/content/en/api/ruby/beta/sessions/events.md b/content/en/api/ruby/beta/sessions/events.md new file mode 100644 index 000000000..586871076 --- /dev/null +++ b/content/en/api/ruby/beta/sessions/events.md @@ -0,0 +1,9626 @@ +# Events + +## List + +`beta.sessions.events.list(session_id, **kwargs) -> PageCursor` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `session_id: String` + +- `limit: Integer` + + Query parameter for limit + +- `order: :asc | :desc` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `:asc` + + - `:desc` + +- `page: String` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.sessions.events.list("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(page) +``` + +## Send + +`beta.sessions.events.send_(session_id, **kwargs) -> BetaManagedAgentsSendSessionEvents` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `session_id: String` + +- `events: Array[BetaManagedAgentsEventParams]` + + Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data: Array[BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | BetaManagedAgentsUserCustomToolResultEvent]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_send_session_events = anthropic.beta.sessions.events.send_( + "sesn_011CZkZAtmR3yMPDzynEDxu7", + events: [{content: [{text: "Where is my order #1234?", type: :text}], type: :"user.message"}] +) + +puts(beta_managed_agents_send_session_events) +``` + +## Stream + +`beta.sessions.events.stream(session_id, **kwargs) -> BetaManagedAgentsStreamSessionEvents` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_stream_session_events = anthropic.beta.sessions.events.stream("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_stream_session_events) +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + +### Beta Managed Agents Agent Message Event + +- `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + +### Beta Managed Agents Base64 Document Source + +- `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + +### Beta Managed Agents Base64 Image Source + +- `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + +### Beta Managed Agents Billing Error + +- `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + +### Beta Managed Agents Document Block + +- `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + +### Beta Managed Agents Event Params + +- `BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams | BetaManagedAgentsUserInterruptEventParams | BetaManagedAgentsUserToolConfirmationEventParams | BetaManagedAgentsUserCustomToolResultEventParams` + + Union type for event parameters that can be sent to a session. + + - `class BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + +### Beta Managed Agents File Image Source + +- `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + +### Beta Managed Agents Image Block + +- `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + +### Beta Managed Agents MCP Authentication Failed Error + +- `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + +### Beta Managed Agents MCP Connection Failed Error + +- `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + +### Beta Managed Agents Model Overloaded Error + +- `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + +### Beta Managed Agents Model Rate Limited Error + +- `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + +### Beta Managed Agents Model Request Failed Error + +- `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + +### Beta Managed Agents Plain Text Document Source + +- `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + +### Beta Managed Agents Retry Status Exhausted + +- `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + +### Beta Managed Agents Retry Status Retrying + +- `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + +### Beta Managed Agents Retry Status Terminal + +- `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + +### Beta Managed Agents Send Session Events + +- `class BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data: Array[BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | BetaManagedAgentsUserCustomToolResultEvent]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + +### Beta Managed Agents Session Error Event + +- `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + +### Beta Managed Agents Session Event + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + +### Beta Managed Agents Session Retries Exhausted + +- `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + +### Beta Managed Agents Session Status Idle Event + +- `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `class BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + +### Beta Managed Agents Stream Session Events + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Beta Managed Agents Text Block + +- `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + +### Beta Managed Agents Unknown Error + +- `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + +### Beta Managed Agents URL Document Source + +- `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `class BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `class BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `class BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `class BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. diff --git a/content/en/api/ruby/beta/sessions/events/list.md b/content/en/api/ruby/beta/sessions/events/list.md new file mode 100644 index 000000000..1c30a4dbd --- /dev/null +++ b/content/en/api/ruby/beta/sessions/events/list.md @@ -0,0 +1,1459 @@ +## List + +`beta.sessions.events.list(session_id, **kwargs) -> PageCursor` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `session_id: String` + +- `limit: Integer` + + Query parameter for limit + +- `order: :asc | :desc` + + Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `:asc` + + - `:desc` + +- `page: String` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.sessions.events.list("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(page) +``` diff --git a/content/en/api/ruby/beta/sessions/events/send.md b/content/en/api/ruby/beta/sessions/events/send.md new file mode 100644 index 000000000..86031d465 --- /dev/null +++ b/content/en/api/ruby/beta/sessions/events/send.md @@ -0,0 +1,818 @@ +## Send + +`beta.sessions.events.send_(session_id, **kwargs) -> BetaManagedAgentsSendSessionEvents` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `session_id: String` + +- `events: Array[BetaManagedAgentsEventParams]` + + Events to send to the `session`. + + - `class BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks for the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `class BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `class BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `class BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data: Array[BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | BetaManagedAgentsUserCustomToolResultEvent]` + + Sent events + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_send_session_events = anthropic.beta.sessions.events.send_( + "sesn_011CZkZAtmR3yMPDzynEDxu7", + events: [{content: [{text: "Where is my order #1234?", type: :text}], type: :"user.message"}] +) + +puts(beta_managed_agents_send_session_events) +``` diff --git a/content/en/api/ruby/beta/sessions/events/stream.md b/content/en/api/ruby/beta/sessions/events/stream.md new file mode 100644 index 000000000..5d36a57ef --- /dev/null +++ b/content/en/api/ruby/beta/sessions/events/stream.md @@ -0,0 +1,1443 @@ +## Stream + +`beta.sessions.events.stream(session_id, **kwargs) -> BetaManagedAgentsStreamSessionEvents` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `class BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + Array of content blocks comprising the user message. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `type: :"user.message"` + + - `:"user.message"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: String` + + Unique identifier for this event. + + - `type: :"user.interrupt"` + + - `:"user.interrupt"` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: String` + + Unique identifier for this event. + + - `result: :allow | :deny` + + UserToolConfirmationResult enum + + - `:allow` + + - `:deny` + + - `tool_use_id: String` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.tool_confirmation"` + + - `:"user.tool_confirmation"` + + - `deny_message: String` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: String` + + Unique identifier for this event. + + - `custom_tool_use_id: String` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: :"user.custom_tool_result"` + + - `:"user.custom_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `class BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the custom tool being called. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.custom_tool_use"` + + - `:"agent.custom_tool_use"` + + - `class BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: String` + + Unique identifier for this event. + + - `content: Array[BetaManagedAgentsTextBlock]` + + Array of text blocks comprising the agent response. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.message"` + + - `:"agent.message"` + + - `class BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thinking"` + + - `:"agent.thinking"` + + - `class BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `mcp_server_name: String` + + Name of the MCP server providing the tool. + + - `name: String` + + Name of the MCP tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_use"` + + - `:"agent.mcp_tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: String` + + Unique identifier for this event. + + - `mcp_tool_use_id: String` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.mcp_tool_result"` + + - `:"agent.mcp_tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: String` + + Unique identifier for this event. + + - `input: Hash[Symbol, untyped]` + + Input parameters for the tool call. + + - `name: String` + + Name of the agent tool being used. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.tool_use"` + + - `:"agent.tool_use"` + + - `evaluated_permission: :allow | :ask | :deny` + + AgentEvaluatedPermission enum + + - `:allow` + + - `:ask` + + - `:deny` + + - `class BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `tool_use_id: String` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: :"agent.tool_result"` + + - `:"agent.tool_result"` + + - `content: Array[BetaManagedAgentsTextBlock | BetaManagedAgentsImageBlock | BetaManagedAgentsDocumentBlock]` + + The result content returned by the tool. + + - `class BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: String` + + The text content. + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `class BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: String` + + Base64-encoded image data. + + - `media_type: String` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the image to fetch. + + - `class BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :image` + + - `:image` + + - `class BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `class BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: String` + + Base64-encoded document data. + + - `media_type: String` + + MIME type of the document (e.g., "application/pdf"). + + - `type: :base64` + + - `:base64` + + - `class BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: String` + + The plain text content. + + - `media_type: :"text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `:"text/plain"` + + - `type: :text` + + - `:text` + + - `class BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: :url` + + - `:url` + + - `url: String` + + URL of the document to fetch. + + - `class BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: String` + + ID of a previously uploaded file. + + - `type: :file` + + - `:file` + + - `type: :document` + + - `:document` + + - `context: String` + + Additional context about the document for the model. + + - `title: String` + + The title of the document. + + - `is_error: bool` + + Whether the tool execution resulted in an error. + + - `class BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"agent.thread_context_compacted"` + + - `:"agent.thread_context_compacted"` + + - `class BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: String` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `class BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :unknown_error` + + - `:unknown_error` + + - `class BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_overloaded_error` + + - `:model_overloaded_error` + + - `class BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_rate_limited_error` + + - `:model_rate_limited_error` + + - `class BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :model_request_failed_error` + + - `:model_request_failed_error` + + - `class BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: String` + + Name of the MCP server that failed to connect. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_connection_failed_error` + + - `:mcp_connection_failed_error` + + - `class BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: String` + + Name of the MCP server that failed authentication. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :mcp_authentication_failed_error` + + - `:mcp_authentication_failed_error` + + - `class BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: String` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `class BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: :retrying` + + - `:retrying` + + - `class BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: :exhausted` + + - `:exhausted` + + - `class BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: :terminal` + + - `:terminal` + + - `type: :billing_error` + + - `:billing_error` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.error"` + + - `:"session.error"` + + - `class BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_rescheduled"` + + - `:"session.status_rescheduled"` + + - `class BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_running"` + + - `:"session.status_running"` + + - `class BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `class BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: :end_turn` + + - `:end_turn` + + - `class BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array[String]` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: :requires_action` + + - `:requires_action` + + - `class BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: :retries_exhausted` + + - `:retries_exhausted` + + - `type: :"session.status_idle"` + + - `:"session.status_idle"` + + - `class BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.status_terminated"` + + - `:"session.status_terminated"` + + - `class BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_start"` + + - `:"span.model_request_start"` + + - `class BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: String` + + Unique identifier for this event. + + - `is_error: bool` + + Whether the model request resulted in an error. + + - `model_request_start_id: String` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: Integer` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: Integer` + + Tokens read from prompt cache in this request. + + - `input_tokens: Integer` + + Input tokens consumed by this request. + + - `output_tokens: Integer` + + Output tokens generated by this request. + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"span.model_request_end"` + + - `:"span.model_request_end"` + + - `class BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: String` + + Unique identifier for this event. + + - `processed_at: Time` + + A timestamp in RFC 3339 format + + - `type: :"session.deleted"` + + - `:"session.deleted"` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_stream_session_events = anthropic.beta.sessions.events.stream("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_stream_session_events) +``` diff --git a/content/en/api/ruby/beta/sessions/list.md b/content/en/api/ruby/beta/sessions/list.md new file mode 100644 index 000000000..f0b6e54cc --- /dev/null +++ b/content/en/api/ruby/beta/sessions/list.md @@ -0,0 +1,545 @@ +## List + +`beta.sessions.list(**kwargs) -> PageCursor` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `agent_id: String` + + Filter sessions created with this agent ID. + +- `agent_version: Integer` + + Filter by agent version. Only applies when agent_id is also set. + +- `created_at_gt: Time` + + Return sessions created after this time (exclusive). + +- `created_at_gte: Time` + + Return sessions created at or after this time (inclusive). + +- `created_at_lt: Time` + + Return sessions created before this time (exclusive). + +- `created_at_lte: Time` + + Return sessions created at or before this time (inclusive). + +- `include_archived: bool` + + When true, includes archived sessions. Default: false (exclude archived). + +- `limit: Integer` + + Maximum number of results to return. + +- `order: :asc | :desc` + + Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `:asc` + + - `:desc` + +- `page: String` + + Opaque pagination cursor from a previous response's next_page. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.sessions.list + +puts(page) +``` diff --git a/content/en/api/ruby/beta/sessions/resources.md b/content/en/api/ruby/beta/sessions/resources.md new file mode 100644 index 000000000..3f97dab2d --- /dev/null +++ b/content/en/api/ruby/beta/sessions/resources.md @@ -0,0 +1,933 @@ +# Resources + +## Add + +`beta.sessions.resources.add(session_id, **kwargs) -> BetaManagedAgentsFileResource` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `session_id: String` + +- `file_id: String` + + ID of a previously uploaded file. + +- `type: :file` + + - `:file` + +- `mount_path: String` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_file_resource = anthropic.beta.sessions.resources.add( + "sesn_011CZkZAtmR3yMPDzynEDxu7", + file_id: "file_011CNha8iCJcU1wXNR6q4V8w", + type: :file +) + +puts(beta_managed_agents_file_resource) +``` + +## List + +`beta.sessions.resources.list(session_id, **kwargs) -> PageCursor` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `session_id: String` + +- `limit: Integer` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `page: String` + + Opaque cursor from a previous response's next_page field. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.sessions.resources.list("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(page) +``` + +## Retrieve + +`beta.sessions.resources.retrieve(resource_id, **kwargs) -> ResourceRetrieveResponse` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `session_id: String` + +- `resource_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +resource = anthropic.beta.sessions.resources.retrieve( + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id: "sesn_011CZkZAtmR3yMPDzynEDxu7" +) + +puts(resource) +``` + +## Update + +`beta.sessions.resources.update(resource_id, **kwargs) -> ResourceUpdateResponse` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `session_id: String` + +- `resource_id: String` + +- `authorization_token: String` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +resource = anthropic.beta.sessions.resources.update( + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id: "sesn_011CZkZAtmR3yMPDzynEDxu7", + authorization_token: "ghp_exampletoken" +) + +puts(resource) +``` + +## Delete + +`beta.sessions.resources.delete(resource_id, **kwargs) -> BetaManagedAgentsDeleteSessionResource` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `session_id: String` + +- `resource_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: String` + + - `type: :session_resource_deleted` + + - `:session_resource_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_delete_session_resource = anthropic.beta.sessions.resources.delete( + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id: "sesn_011CZkZAtmR3yMPDzynEDxu7" +) + +puts(beta_managed_agents_delete_session_resource) +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `class BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: String` + + - `type: :session_resource_deleted` + + - `:session_resource_deleted` + +### Beta Managed Agents File Resource + +- `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + +### Beta Managed Agents Session Resource + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Resource Retrieve Response + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Resource Update Response + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format diff --git a/content/en/api/ruby/beta/sessions/resources/add.md b/content/en/api/ruby/beta/sessions/resources/add.md new file mode 100644 index 000000000..9ccebd41c --- /dev/null +++ b/content/en/api/ruby/beta/sessions/resources/add.md @@ -0,0 +1,111 @@ +## Add + +`beta.sessions.resources.add(session_id, **kwargs) -> BetaManagedAgentsFileResource` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `session_id: String` + +- `file_id: String` + + ID of a previously uploaded file. + +- `type: :file` + + - `:file` + +- `mount_path: String` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_file_resource = anthropic.beta.sessions.resources.add( + "sesn_011CZkZAtmR3yMPDzynEDxu7", + file_id: "file_011CNha8iCJcU1wXNR6q4V8w", + type: :file +) + +puts(beta_managed_agents_file_resource) +``` diff --git a/content/en/api/ruby/beta/sessions/resources/delete.md b/content/en/api/ruby/beta/sessions/resources/delete.md new file mode 100644 index 000000000..2ed7a2dc9 --- /dev/null +++ b/content/en/api/ruby/beta/sessions/resources/delete.md @@ -0,0 +1,90 @@ +## Delete + +`beta.sessions.resources.delete(resource_id, **kwargs) -> BetaManagedAgentsDeleteSessionResource` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `session_id: String` + +- `resource_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: String` + + - `type: :session_resource_deleted` + + - `:session_resource_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_delete_session_resource = anthropic.beta.sessions.resources.delete( + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id: "sesn_011CZkZAtmR3yMPDzynEDxu7" +) + +puts(beta_managed_agents_delete_session_resource) +``` diff --git a/content/en/api/ruby/beta/sessions/resources/list.md b/content/en/api/ruby/beta/sessions/resources/list.md new file mode 100644 index 000000000..a04a30826 --- /dev/null +++ b/content/en/api/ruby/beta/sessions/resources/list.md @@ -0,0 +1,147 @@ +## List + +`beta.sessions.resources.list(session_id, **kwargs) -> PageCursor` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `session_id: String` + +- `limit: Integer` + + Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + +- `page: String` + + Opaque cursor from a previous response's next_page field. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.sessions.resources.list("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(page) +``` diff --git a/content/en/api/ruby/beta/sessions/resources/retrieve.md b/content/en/api/ruby/beta/sessions/resources/retrieve.md new file mode 100644 index 000000000..92edb6f11 --- /dev/null +++ b/content/en/api/ruby/beta/sessions/resources/retrieve.md @@ -0,0 +1,146 @@ +## Retrieve + +`beta.sessions.resources.retrieve(resource_id, **kwargs) -> ResourceRetrieveResponse` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `session_id: String` + +- `resource_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +resource = anthropic.beta.sessions.resources.retrieve( + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id: "sesn_011CZkZAtmR3yMPDzynEDxu7" +) + +puts(resource) +``` diff --git a/content/en/api/ruby/beta/sessions/resources/update.md b/content/en/api/ruby/beta/sessions/resources/update.md new file mode 100644 index 000000000..2529da5b5 --- /dev/null +++ b/content/en/api/ruby/beta/sessions/resources/update.md @@ -0,0 +1,151 @@ +## Update + +`beta.sessions.resources.update(resource_id, **kwargs) -> ResourceUpdateResponse` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `session_id: String` + +- `resource_id: String` + +- `authorization_token: String` + + New authorization token for the resource. Currently only `github_repository` resources support token rotation. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +resource = anthropic.beta.sessions.resources.update( + "sesrsc_011CZkZBJq5dWxk9fVLNcPht", + session_id: "sesn_011CZkZAtmR3yMPDzynEDxu7", + authorization_token: "ghp_exampletoken" +) + +puts(resource) +``` diff --git a/content/en/api/ruby/beta/sessions/retrieve.md b/content/en/api/ruby/beta/sessions/retrieve.md new file mode 100644 index 000000000..c22d132b6 --- /dev/null +++ b/content/en/api/ruby/beta/sessions/retrieve.md @@ -0,0 +1,503 @@ +## Retrieve + +`beta.sessions.retrieve(session_id, **kwargs) -> BetaManagedAgentsSession` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `session_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_session = anthropic.beta.sessions.retrieve("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_session) +``` diff --git a/content/en/api/ruby/beta/sessions/update.md b/content/en/api/ruby/beta/sessions/update.md new file mode 100644 index 000000000..abd563b36 --- /dev/null +++ b/content/en/api/ruby/beta/sessions/update.md @@ -0,0 +1,515 @@ +## Update + +`beta.sessions.update(session_id, **kwargs) -> BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `session_id: String` + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + +- `title: String` + + Human-readable session title. + +- `vault_ids: Array[String]` + + Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: String` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: String` + + - `description: String` + + - `mcp_servers: Array[BetaManagedAgentsMCPServerURLDefinition]` + + - `name: String` + + - `type: :url` + + - `:url` + + - `url: String` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 5 more` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `:"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `:"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `:"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `:"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `:"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `:"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `:"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `String` + + - `speed: :standard | :fast` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `:standard` + + - `:fast` + + - `name: String` + + - `skills: Array[BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill]` + + - `class BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: String` + + - `type: :anthropic` + + - `:anthropic` + + - `version: String` + + - `class BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: String` + + - `type: :custom` + + - `:custom` + + - `version: String` + + - `system_: String` + + - `tools: Array[BetaManagedAgentsAgentToolset20260401 | BetaManagedAgentsMCPToolset | BetaManagedAgentsCustomTool]` + + - `class BetaManagedAgentsAgentToolset20260401` + + - `configs: Array[BetaManagedAgentsAgentToolConfig]` + + - `enabled: bool` + + - `name: :bash | :edit | :read | 5 more` + + Built-in agent tool identifier. + + - `:bash` + + - `:edit` + + - `:read` + + - `:write` + + - `:glob` + + - `:grep` + + - `:web_fetch` + + - `:web_search` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `type: :agent_toolset_20260401` + + - `:agent_toolset_20260401` + + - `class BetaManagedAgentsMCPToolset` + + - `configs: Array[BetaManagedAgentsMCPToolConfig]` + + - `enabled: bool` + + - `name: String` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: bool` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `class BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: :always_allow` + + - `:always_allow` + + - `class BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: :always_ask` + + - `:always_ask` + + - `mcp_server_name: String` + + - `type: :mcp_toolset` + + - `:mcp_toolset` + + - `class BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: String` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties: Hash[Symbol, untyped]` + + JSON Schema properties defining the tool's input parameters. + + - `required: Array[String]` + + List of required property names. + + - `type: :object` + + Must be 'object' for tool input schemas. + + - `:object` + + - `name: String` + + - `type: :custom` + + - `:custom` + + - `type: :agent` + + - `:agent` + + - `version: Integer` + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `environment_id: String` + + - `metadata: Hash[Symbol, String]` + + - `resources: Array[BetaManagedAgentsSessionResource]` + + - `class BetaManagedAgentsGitHubRepositoryResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `mount_path: String` + + - `type: :github_repository` + + - `:github_repository` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `url: String` + + - `checkout: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout` + + - `class BetaManagedAgentsBranchCheckout` + + - `name: String` + + Branch name to check out. + + - `type: :branch` + + - `:branch` + + - `class BetaManagedAgentsCommitCheckout` + + - `sha: String` + + Full commit SHA to check out. + + - `type: :commit` + + - `:commit` + + - `class BetaManagedAgentsFileResource` + + - `id: String` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `file_id: String` + + - `mount_path: String` + + - `type: :file` + + - `:file` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds: Float` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds: Float` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: :rescheduling | :running | :idle | :terminated` + + SessionStatus enum + + - `:rescheduling` + + - `:running` + + - `:idle` + + - `:terminated` + + - `title: String` + + - `type: :session` + + - `:session` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens: Integer` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens: Integer` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens: Integer` + + Total tokens read from prompt cache. + + - `input_tokens: Integer` + + Total input tokens consumed across all turns. + + - `output_tokens: Integer` + + Total output tokens generated across all turns. + + - `vault_ids: Array[String]` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_session = anthropic.beta.sessions.update("sesn_011CZkZAtmR3yMPDzynEDxu7") + +puts(beta_managed_agents_session) +``` diff --git a/content/en/api/ruby/beta/skills.md b/content/en/api/ruby/beta/skills.md index 8cd66573d..812536a3a 100644 --- a/content/en/api/ruby/beta/skills.md +++ b/content/en/api/ruby/beta/skills.md @@ -28,7 +28,7 @@ Create Skill - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -72,8 +72,6 @@ Create Skill - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class SkillCreateResponse` @@ -168,7 +166,7 @@ List Skills - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -212,8 +210,6 @@ List Skills - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class SkillListResponse` @@ -293,7 +289,7 @@ Get Skill - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -337,8 +333,6 @@ Get Skill - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class SkillRetrieveResponse` @@ -418,7 +412,7 @@ Delete Skill - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -462,8 +456,6 @@ Delete Skill - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class SkillDeleteResponse` @@ -675,7 +667,7 @@ Create Skill Version - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -719,8 +711,6 @@ Create Skill Version - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionCreateResponse` @@ -813,7 +803,7 @@ List Skill Versions - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -857,8 +847,6 @@ List Skill Versions - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionListResponse` @@ -947,7 +935,7 @@ Get Skill Version - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -991,8 +979,6 @@ Get Skill Version - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionRetrieveResponse` @@ -1081,7 +1067,7 @@ Delete Skill Version - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -1125,8 +1111,6 @@ Delete Skill Version - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionDeleteResponse` diff --git a/content/en/api/ruby/beta/skills/create.md b/content/en/api/ruby/beta/skills/create.md index 9faa93783..401c02e79 100644 --- a/content/en/api/ruby/beta/skills/create.md +++ b/content/en/api/ruby/beta/skills/create.md @@ -26,7 +26,7 @@ Create Skill - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -70,8 +70,6 @@ Create Skill - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class SkillCreateResponse` diff --git a/content/en/api/ruby/beta/skills/delete.md b/content/en/api/ruby/beta/skills/delete.md index 37a673fda..856c41f23 100644 --- a/content/en/api/ruby/beta/skills/delete.md +++ b/content/en/api/ruby/beta/skills/delete.md @@ -20,7 +20,7 @@ Delete Skill - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Delete Skill - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class SkillDeleteResponse` diff --git a/content/en/api/ruby/beta/skills/list.md b/content/en/api/ruby/beta/skills/list.md index bbf318c76..d8f6da160 100644 --- a/content/en/api/ruby/beta/skills/list.md +++ b/content/en/api/ruby/beta/skills/list.md @@ -35,7 +35,7 @@ List Skills - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -79,8 +79,6 @@ List Skills - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class SkillListResponse` diff --git a/content/en/api/ruby/beta/skills/retrieve.md b/content/en/api/ruby/beta/skills/retrieve.md index 23943eec5..b11a883ea 100644 --- a/content/en/api/ruby/beta/skills/retrieve.md +++ b/content/en/api/ruby/beta/skills/retrieve.md @@ -20,7 +20,7 @@ Get Skill - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Get Skill - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class SkillRetrieveResponse` diff --git a/content/en/api/ruby/beta/skills/versions.md b/content/en/api/ruby/beta/skills/versions.md index cc02625b2..50ea65a71 100644 --- a/content/en/api/ruby/beta/skills/versions.md +++ b/content/en/api/ruby/beta/skills/versions.md @@ -28,7 +28,7 @@ Create Skill Version - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -72,8 +72,6 @@ Create Skill Version - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionCreateResponse` @@ -166,7 +164,7 @@ List Skill Versions - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -210,8 +208,6 @@ List Skill Versions - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionListResponse` @@ -300,7 +296,7 @@ Get Skill Version - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -344,8 +340,6 @@ Get Skill Version - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionRetrieveResponse` @@ -434,7 +428,7 @@ Delete Skill Version - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -478,8 +472,6 @@ Delete Skill Version - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionDeleteResponse` diff --git a/content/en/api/ruby/beta/skills/versions/create.md b/content/en/api/ruby/beta/skills/versions/create.md index 0c72e169b..e6cb486de 100644 --- a/content/en/api/ruby/beta/skills/versions/create.md +++ b/content/en/api/ruby/beta/skills/versions/create.md @@ -26,7 +26,7 @@ Create Skill Version - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -70,8 +70,6 @@ Create Skill Version - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionCreateResponse` diff --git a/content/en/api/ruby/beta/skills/versions/delete.md b/content/en/api/ruby/beta/skills/versions/delete.md index 543221a40..3f22bb13a 100644 --- a/content/en/api/ruby/beta/skills/versions/delete.md +++ b/content/en/api/ruby/beta/skills/versions/delete.md @@ -26,7 +26,7 @@ Delete Skill Version - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -70,8 +70,6 @@ Delete Skill Version - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionDeleteResponse` diff --git a/content/en/api/ruby/beta/skills/versions/list.md b/content/en/api/ruby/beta/skills/versions/list.md index da57543fa..d0ea1c415 100644 --- a/content/en/api/ruby/beta/skills/versions/list.md +++ b/content/en/api/ruby/beta/skills/versions/list.md @@ -30,7 +30,7 @@ List Skill Versions - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ List Skill Versions - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionListResponse` diff --git a/content/en/api/ruby/beta/skills/versions/retrieve.md b/content/en/api/ruby/beta/skills/versions/retrieve.md index f978b5772..738d445db 100644 --- a/content/en/api/ruby/beta/skills/versions/retrieve.md +++ b/content/en/api/ruby/beta/skills/versions/retrieve.md @@ -26,7 +26,7 @@ Get Skill Version - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -70,8 +70,6 @@ Get Skill Version - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class VersionRetrieveResponse` diff --git a/content/en/api/ruby/beta/vaults.md b/content/en/api/ruby/beta/vaults.md new file mode 100644 index 000000000..9100a7412 --- /dev/null +++ b/content/en/api/ruby/beta/vaults.md @@ -0,0 +1,2616 @@ +# Vaults + +## Create + +`beta.vaults.create(**kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `display_name: String` + + Human-readable name for the vault. 1-255 characters. + +- `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata to attach to the vault. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_vault = anthropic.beta.vaults.create(display_name: "Example vault") + +puts(beta_managed_agents_vault) +``` + +## List + +`beta.vaults.list(**kwargs) -> PageCursor` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `include_archived: bool` + + Whether to include archived vaults in the results. + +- `limit: Integer` + + Maximum number of vaults to return per page. Defaults to 20, maximum 100. + +- `page: String` + + Opaque pagination token from a previous `list_vaults` response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.vaults.list + +puts(page) +``` + +## Retrieve + +`beta.vaults.retrieve(vault_id, **kwargs) -> BetaManagedAgentsVault` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `vault_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_vault = anthropic.beta.vaults.retrieve("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(beta_managed_agents_vault) +``` + +## Update + +`beta.vaults.update(vault_id, **kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `vault_id: String` + +- `display_name: String` + + Updated human-readable name for the vault. 1-255 characters. + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_vault = anthropic.beta.vaults.update("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(beta_managed_agents_vault) +``` + +## Delete + +`beta.vaults.delete(vault_id, **kwargs) -> BetaManagedAgentsDeletedVault` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `vault_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedVault` + + Confirmation of a deleted vault. + + - `id: String` + + Unique identifier of the deleted vault. + + - `type: :vault_deleted` + + - `:vault_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_deleted_vault = anthropic.beta.vaults.delete("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(beta_managed_agents_deleted_vault) +``` + +## Archive + +`beta.vaults.archive(vault_id, **kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `vault_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_vault = anthropic.beta.vaults.archive("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(beta_managed_agents_vault) +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `class BetaManagedAgentsDeletedVault` + + Confirmation of a deleted vault. + + - `id: String` + + Unique identifier of the deleted vault. + + - `type: :vault_deleted` + + - `:vault_deleted` + +### Beta Managed Agents Vault + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`beta.vaults.credentials.create(vault_id, **kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vault_id: String` + +- `auth: BetaManagedAgentsMCPOAuthCreateParams | BetaManagedAgentsStaticBearerCreateParams` + + Authentication details for creating a credential. + + - `class BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: String` + + OAuth access token. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: String` + + OAuth client ID. + + - `refresh_token: String` + + OAuth refresh token. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: String` + + Static bearer token value. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + +- `display_name: String` + + Human-readable name for the credential. Up to 255 characters. + +- `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata to attach to the credential. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.create( + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + auth: { + token: "bearer_exampletoken", + mcp_server_url: "https://example-server.modelcontextprotocol.io/sse", + type: :static_bearer + } +) + +puts(beta_managed_agents_credential) +``` + +## List + +`beta.vaults.credentials.list(vault_id, **kwargs) -> PageCursor` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vault_id: String` + +- `include_archived: bool` + + Whether to include archived credentials in the results. + +- `limit: Integer` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `page: String` + + Opaque pagination token from a previous `list_credentials` response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.vaults.credentials.list("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(page) +``` + +## Retrieve + +`beta.vaults.credentials.retrieve(credential_id, **kwargs) -> BetaManagedAgentsCredential` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.retrieve( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_credential) +``` + +## Update + +`beta.vaults.credentials.update(credential_id, **kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `auth: BetaManagedAgentsMCPOAuthUpdateParams | BetaManagedAgentsStaticBearerUpdateParams` + + Updated authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `access_token: String` + + Updated OAuth access token. + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: String` + + Updated OAuth refresh token. + + - `scope: String` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: :static_bearer` + + - `:static_bearer` + + - `token: String` + + Updated static bearer token value. + +- `display_name: String` + + Updated human-readable name for the credential. 1-255 characters. + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.update( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_credential) +``` + +## Delete + +`beta.vaults.credentials.delete(credential_id, **kwargs) -> BetaManagedAgentsDeletedCredential` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: String` + + Unique identifier of the deleted credential. + + - `type: :vault_credential_deleted` + + - `:vault_credential_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_deleted_credential = anthropic.beta.vaults.credentials.delete( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_deleted_credential) +``` + +## Archive + +`beta.vaults.credentials.archive(credential_id, **kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.archive( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_credential) +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `class BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: String` + + Unique identifier of the deleted credential. + + - `type: :vault_credential_deleted` + + - `:vault_credential_deleted` + +### Beta Managed Agents MCP OAuth Auth Response + +- `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `class BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: String` + + OAuth access token. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: String` + + OAuth client ID. + + - `refresh_token: String` + + OAuth refresh token. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `class BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: String` + + OAuth client ID. + + - `refresh_token: String` + + OAuth refresh token. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `class BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `class BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: String` + + Updated OAuth refresh token. + + - `scope: String` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `class BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `access_token: String` + + Updated OAuth access token. + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: String` + + Updated OAuth refresh token. + + - `scope: String` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + +### Beta Managed Agents Static Bearer Create Params + +- `class BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: String` + + Static bearer token value. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + +### Beta Managed Agents Static Bearer Update Params + +- `class BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: :static_bearer` + + - `:static_bearer` + + - `token: String` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. diff --git a/content/en/api/ruby/beta/vaults/archive.md b/content/en/api/ruby/beta/vaults/archive.md new file mode 100644 index 000000000..53f4621ff --- /dev/null +++ b/content/en/api/ruby/beta/vaults/archive.md @@ -0,0 +1,107 @@ +## Archive + +`beta.vaults.archive(vault_id, **kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `vault_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_vault = anthropic.beta.vaults.archive("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(beta_managed_agents_vault) +``` diff --git a/content/en/api/ruby/beta/vaults/create.md b/content/en/api/ruby/beta/vaults/create.md new file mode 100644 index 000000000..9ae5ade68 --- /dev/null +++ b/content/en/api/ruby/beta/vaults/create.md @@ -0,0 +1,113 @@ +## Create + +`beta.vaults.create(**kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `display_name: String` + + Human-readable name for the vault. 1-255 characters. + +- `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata to attach to the vault. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_vault = anthropic.beta.vaults.create(display_name: "Example vault") + +puts(beta_managed_agents_vault) +``` diff --git a/content/en/api/ruby/beta/vaults/credentials.md b/content/en/api/ruby/beta/vaults/credentials.md new file mode 100644 index 000000000..04dcabd85 --- /dev/null +++ b/content/en/api/ruby/beta/vaults/credentials.md @@ -0,0 +1,1912 @@ +# Credentials + +## Create + +`beta.vaults.credentials.create(vault_id, **kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vault_id: String` + +- `auth: BetaManagedAgentsMCPOAuthCreateParams | BetaManagedAgentsStaticBearerCreateParams` + + Authentication details for creating a credential. + + - `class BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: String` + + OAuth access token. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: String` + + OAuth client ID. + + - `refresh_token: String` + + OAuth refresh token. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: String` + + Static bearer token value. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + +- `display_name: String` + + Human-readable name for the credential. Up to 255 characters. + +- `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata to attach to the credential. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.create( + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + auth: { + token: "bearer_exampletoken", + mcp_server_url: "https://example-server.modelcontextprotocol.io/sse", + type: :static_bearer + } +) + +puts(beta_managed_agents_credential) +``` + +## List + +`beta.vaults.credentials.list(vault_id, **kwargs) -> PageCursor` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vault_id: String` + +- `include_archived: bool` + + Whether to include archived credentials in the results. + +- `limit: Integer` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `page: String` + + Opaque pagination token from a previous `list_credentials` response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.vaults.credentials.list("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(page) +``` + +## Retrieve + +`beta.vaults.credentials.retrieve(credential_id, **kwargs) -> BetaManagedAgentsCredential` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.retrieve( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_credential) +``` + +## Update + +`beta.vaults.credentials.update(credential_id, **kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `auth: BetaManagedAgentsMCPOAuthUpdateParams | BetaManagedAgentsStaticBearerUpdateParams` + + Updated authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `access_token: String` + + Updated OAuth access token. + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: String` + + Updated OAuth refresh token. + + - `scope: String` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: :static_bearer` + + - `:static_bearer` + + - `token: String` + + Updated static bearer token value. + +- `display_name: String` + + Updated human-readable name for the credential. 1-255 characters. + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.update( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_credential) +``` + +## Delete + +`beta.vaults.credentials.delete(credential_id, **kwargs) -> BetaManagedAgentsDeletedCredential` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: String` + + Unique identifier of the deleted credential. + + - `type: :vault_credential_deleted` + + - `:vault_credential_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_deleted_credential = anthropic.beta.vaults.credentials.delete( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_deleted_credential) +``` + +## Archive + +`beta.vaults.credentials.archive(credential_id, **kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.archive( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_credential) +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `class BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: String` + + Unique identifier of the deleted credential. + + - `type: :vault_credential_deleted` + + - `:vault_credential_deleted` + +### Beta Managed Agents MCP OAuth Auth Response + +- `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `class BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: String` + + OAuth access token. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: String` + + OAuth client ID. + + - `refresh_token: String` + + OAuth refresh token. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `class BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: String` + + OAuth client ID. + + - `refresh_token: String` + + OAuth refresh token. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `class BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `class BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: String` + + Updated OAuth refresh token. + + - `scope: String` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `class BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `access_token: String` + + Updated OAuth access token. + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: String` + + Updated OAuth refresh token. + + - `scope: String` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + +### Beta Managed Agents Static Bearer Create Params + +- `class BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: String` + + Static bearer token value. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + +### Beta Managed Agents Static Bearer Update Params + +- `class BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: :static_bearer` + + - `:static_bearer` + + - `token: String` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. diff --git a/content/en/api/ruby/beta/vaults/credentials/archive.md b/content/en/api/ruby/beta/vaults/credentials/archive.md new file mode 100644 index 000000000..d9d2ea466 --- /dev/null +++ b/content/en/api/ruby/beta/vaults/credentials/archive.md @@ -0,0 +1,196 @@ +## Archive + +`beta.vaults.credentials.archive(credential_id, **kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.archive( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_credential) +``` diff --git a/content/en/api/ruby/beta/vaults/credentials/create.md b/content/en/api/ruby/beta/vaults/credentials/create.md new file mode 100644 index 000000000..9a77872be --- /dev/null +++ b/content/en/api/ruby/beta/vaults/credentials/create.md @@ -0,0 +1,306 @@ +## Create + +`beta.vaults.credentials.create(vault_id, **kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vault_id: String` + +- `auth: BetaManagedAgentsMCPOAuthCreateParams | BetaManagedAgentsStaticBearerCreateParams` + + Authentication details for creating a credential. + + - `class BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: String` + + OAuth access token. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: String` + + OAuth client ID. + + - `refresh_token: String` + + OAuth refresh token. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: String` + + OAuth client secret. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: String` + + Static bearer token value. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + +- `display_name: String` + + Human-readable name for the credential. Up to 255 characters. + +- `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata to attach to the credential. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.create( + "vlt_011CZkZDLs7fYzm1hXNPeRjv", + auth: { + token: "bearer_exampletoken", + mcp_server_url: "https://example-server.modelcontextprotocol.io/sse", + type: :static_bearer + } +) + +puts(beta_managed_agents_credential) +``` diff --git a/content/en/api/ruby/beta/vaults/credentials/delete.md b/content/en/api/ruby/beta/vaults/credentials/delete.md new file mode 100644 index 000000000..7d995835c --- /dev/null +++ b/content/en/api/ruby/beta/vaults/credentials/delete.md @@ -0,0 +1,92 @@ +## Delete + +`beta.vaults.credentials.delete(credential_id, **kwargs) -> BetaManagedAgentsDeletedCredential` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: String` + + Unique identifier of the deleted credential. + + - `type: :vault_credential_deleted` + + - `:vault_credential_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_deleted_credential = anthropic.beta.vaults.credentials.delete( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_deleted_credential) +``` diff --git a/content/en/api/ruby/beta/vaults/credentials/list.md b/content/en/api/ruby/beta/vaults/credentials/list.md new file mode 100644 index 000000000..9b95c035b --- /dev/null +++ b/content/en/api/ruby/beta/vaults/credentials/list.md @@ -0,0 +1,203 @@ +## List + +`beta.vaults.credentials.list(vault_id, **kwargs) -> PageCursor` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vault_id: String` + +- `include_archived: bool` + + Whether to include archived credentials in the results. + +- `limit: Integer` + + Maximum number of credentials to return per page. Defaults to 20, maximum 100. + +- `page: String` + + Opaque pagination token from a previous `list_credentials` response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.vaults.credentials.list("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(page) +``` diff --git a/content/en/api/ruby/beta/vaults/credentials/retrieve.md b/content/en/api/ruby/beta/vaults/credentials/retrieve.md new file mode 100644 index 000000000..296752c07 --- /dev/null +++ b/content/en/api/ruby/beta/vaults/credentials/retrieve.md @@ -0,0 +1,196 @@ +## Retrieve + +`beta.vaults.credentials.retrieve(credential_id, **kwargs) -> BetaManagedAgentsCredential` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.retrieve( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_credential) +``` diff --git a/content/en/api/ruby/beta/vaults/credentials/update.md b/content/en/api/ruby/beta/vaults/credentials/update.md new file mode 100644 index 000000000..a397097d3 --- /dev/null +++ b/content/en/api/ruby/beta/vaults/credentials/update.md @@ -0,0 +1,276 @@ +## Update + +`beta.vaults.credentials.update(credential_id, **kwargs) -> BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `vault_id: String` + +- `credential_id: String` + +- `auth: BetaManagedAgentsMCPOAuthUpdateParams | BetaManagedAgentsStaticBearerUpdateParams` + + Updated authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `access_token: String` + + Updated OAuth access token. + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token: String` + + Updated OAuth refresh token. + + - `scope: String` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `client_secret: String` + + Updated OAuth client secret. + + - `class BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: :static_bearer` + + - `:static_bearer` + + - `token: String` + + Updated static bearer token value. + +- `display_name: String` + + Updated human-readable name for the credential. 1-255 characters. + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: String` + + Unique identifier for the credential. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `class BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :mcp_oauth` + + - `:mcp_oauth` + + - `expires_at: Time` + + A timestamp in RFC 3339 format + + - `refresh: BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: String` + + OAuth client ID. + + - `token_endpoint: String` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `class BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: :none` + + - `:none` + + - `class BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: :client_secret_basic` + + - `:client_secret_basic` + + - `class BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: :client_secret_post` + + - `:client_secret_post` + + - `resource: String` + + OAuth resource indicator. + + - `scope: String` + + OAuth scope for the refresh request. + + - `class BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: String` + + URL of the MCP server this credential authenticates against. + + - `type: :static_bearer` + + - `:static_bearer` + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the credential. + + - `type: :vault_credential` + + - `:vault_credential` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + + - `vault_id: String` + + Identifier of the vault this credential belongs to. + + - `display_name: String` + + Human-readable name for the credential. + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_credential = anthropic.beta.vaults.credentials.update( + "vcrd_011CZkZEMt8gZan2iYOQfSkw", + vault_id: "vlt_011CZkZDLs7fYzm1hXNPeRjv" +) + +puts(beta_managed_agents_credential) +``` diff --git a/content/en/api/ruby/beta/vaults/delete.md b/content/en/api/ruby/beta/vaults/delete.md new file mode 100644 index 000000000..6c8d60a76 --- /dev/null +++ b/content/en/api/ruby/beta/vaults/delete.md @@ -0,0 +1,87 @@ +## Delete + +`beta.vaults.delete(vault_id, **kwargs) -> BetaManagedAgentsDeletedVault` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `vault_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsDeletedVault` + + Confirmation of a deleted vault. + + - `id: String` + + Unique identifier of the deleted vault. + + - `type: :vault_deleted` + + - `:vault_deleted` + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_deleted_vault = anthropic.beta.vaults.delete("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(beta_managed_agents_deleted_vault) +``` diff --git a/content/en/api/ruby/beta/vaults/list.md b/content/en/api/ruby/beta/vaults/list.md new file mode 100644 index 000000000..73d3c8837 --- /dev/null +++ b/content/en/api/ruby/beta/vaults/list.md @@ -0,0 +1,117 @@ +## List + +`beta.vaults.list(**kwargs) -> PageCursor` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `include_archived: bool` + + Whether to include archived vaults in the results. + +- `limit: Integer` + + Maximum number of vaults to return per page. Defaults to 20, maximum 100. + +- `page: String` + + Opaque pagination token from a previous `list_vaults` response. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +page = anthropic.beta.vaults.list + +puts(page) +``` diff --git a/content/en/api/ruby/beta/vaults/retrieve.md b/content/en/api/ruby/beta/vaults/retrieve.md new file mode 100644 index 000000000..7b614deab --- /dev/null +++ b/content/en/api/ruby/beta/vaults/retrieve.md @@ -0,0 +1,107 @@ +## Retrieve + +`beta.vaults.retrieve(vault_id, **kwargs) -> BetaManagedAgentsVault` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `vault_id: String` + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_vault = anthropic.beta.vaults.retrieve("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(beta_managed_agents_vault) +``` diff --git a/content/en/api/ruby/beta/vaults/update.md b/content/en/api/ruby/beta/vaults/update.md new file mode 100644 index 000000000..24658052b --- /dev/null +++ b/content/en/api/ruby/beta/vaults/update.md @@ -0,0 +1,115 @@ +## Update + +`beta.vaults.update(vault_id, **kwargs) -> BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `vault_id: String` + +- `display_name: String` + + Updated human-readable name for the vault. 1-255 characters. + +- `metadata: Hash[Symbol, String]` + + Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + +- `betas: Array[AnthropicBeta]` + + Optional header to specify the beta version(s) you want to use. + + - `String` + + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` + + - `:"message-batches-2024-09-24"` + + - `:"prompt-caching-2024-07-31"` + + - `:"computer-use-2024-10-22"` + + - `:"computer-use-2025-01-24"` + + - `:"pdfs-2024-09-25"` + + - `:"token-counting-2024-11-01"` + + - `:"token-efficient-tools-2025-02-19"` + + - `:"output-128k-2025-02-19"` + + - `:"files-api-2025-04-14"` + + - `:"mcp-client-2025-04-04"` + + - `:"mcp-client-2025-11-20"` + + - `:"dev-full-thinking-2025-05-14"` + + - `:"interleaved-thinking-2025-05-14"` + + - `:"code-execution-2025-05-22"` + + - `:"extended-cache-ttl-2025-04-11"` + + - `:"context-1m-2025-08-07"` + + - `:"context-management-2025-06-27"` + + - `:"model-context-window-exceeded-2025-08-26"` + + - `:"skills-2025-10-02"` + + - `:"fast-mode-2026-02-01"` + + - `:"output-300k-2026-03-24"` + +### Returns + +- `class BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: String` + + Unique identifier for the vault. + + - `archived_at: Time` + + A timestamp in RFC 3339 format + + - `created_at: Time` + + A timestamp in RFC 3339 format + + - `display_name: String` + + Human-readable name for the vault. + + - `metadata: Hash[Symbol, String]` + + Arbitrary key-value metadata attached to the vault. + + - `type: :vault` + + - `:vault` + + - `updated_at: Time` + + A timestamp in RFC 3339 format + +### Example + +```ruby +require "anthropic" + +anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") + +beta_managed_agents_vault = anthropic.beta.vaults.update("vlt_011CZkZDLs7fYzm1hXNPeRjv") + +puts(beta_managed_agents_vault) +``` diff --git a/content/en/api/ruby/completions.md b/content/en/api/ruby/completions.md index 197e463e1..dfda2d186 100644 --- a/content/en/api/ruby/completions.md +++ b/content/en/api/ruby/completions.md @@ -26,15 +26,19 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -168,7 +172,7 @@ Future models and features will not be compatible with Text Completions. See our - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -212,8 +216,6 @@ Future models and features will not be compatible with Text Completions. See our - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class Completion` @@ -234,15 +236,19 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -328,7 +334,7 @@ anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") completion = anthropic.completions.create( max_tokens_to_sample: 256, - model: :"claude-opus-4-6", + model: :"claude-mythos-preview", prompt: "\n\nHuman: Hello, world!\n\nAssistant:" ) @@ -357,15 +363,19 @@ puts(completion) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` diff --git a/content/en/api/ruby/completions/create.md b/content/en/api/ruby/completions/create.md index 4a10a6330..6151cb4c2 100644 --- a/content/en/api/ruby/completions/create.md +++ b/content/en/api/ruby/completions/create.md @@ -24,15 +24,19 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -166,7 +170,7 @@ Future models and features will not be compatible with Text Completions. See our - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -210,8 +214,6 @@ Future models and features will not be compatible with Text Completions. See our - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class Completion` @@ -232,15 +234,19 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -326,7 +332,7 @@ anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") completion = anthropic.completions.create( max_tokens_to_sample: 256, - model: :"claude-opus-4-6", + model: :"claude-mythos-preview", prompt: "\n\nHuman: Hello, world!\n\nAssistant:" ) diff --git a/content/en/api/ruby/messages.md b/content/en/api/ruby/messages.md index 7d78be1b9..ba97950c6 100644 --- a/content/en/api/ruby/messages.md +++ b/content/en/api/ruby/messages.md @@ -2305,15 +2305,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -4532,15 +4536,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -7052,15 +7060,19 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -8515,7 +8527,10 @@ require "anthropic" anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") -message_tokens_count = anthropic.messages.count_tokens(messages: [{content: "string", role: :user}], model: :"claude-opus-4-6") +message_tokens_count = anthropic.messages.count_tokens( + messages: [{content: "string", role: :user}], + model: :"claude-mythos-preview" +) puts(message_tokens_count) ``` @@ -14210,15 +14225,19 @@ puts(message_tokens_count) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -17741,21 +17760,25 @@ puts(message_tokens_count) ### Model -- `Model = :"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more | String` +- `Model = :"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more | String` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -19622,15 +19645,19 @@ puts(message_tokens_count) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -20558,15 +20585,19 @@ puts(message_tokens_count) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -29653,15 +29684,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -32437,15 +32472,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -33705,15 +33744,19 @@ puts(message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -34769,15 +34812,19 @@ puts(message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -35795,15 +35842,19 @@ puts(message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` diff --git a/content/en/api/ruby/messages/batches.md b/content/en/api/ruby/messages/batches.md index ef0287ef3..e4c88d460 100644 --- a/content/en/api/ruby/messages/batches.md +++ b/content/en/api/ruby/messages/batches.md @@ -2321,15 +2321,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -5105,15 +5109,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -6373,15 +6381,19 @@ puts(message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -7437,15 +7449,19 @@ puts(message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -8463,15 +8479,19 @@ puts(message_batch_individual_response) See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` diff --git a/content/en/api/ruby/messages/batches/create.md b/content/en/api/ruby/messages/batches/create.md index a9efd1d1d..4653536d9 100644 --- a/content/en/api/ruby/messages/batches/create.md +++ b/content/en/api/ruby/messages/batches/create.md @@ -2319,15 +2319,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` diff --git a/content/en/api/ruby/messages/batches/results.md b/content/en/api/ruby/messages/batches/results.md index 0b673d040..0fdb6c4bf 100644 --- a/content/en/api/ruby/messages/batches/results.md +++ b/content/en/api/ruby/messages/batches/results.md @@ -747,15 +747,19 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` diff --git a/content/en/api/ruby/messages/count_tokens.md b/content/en/api/ruby/messages/count_tokens.md index 07430eda0..b967fecf6 100644 --- a/content/en/api/ruby/messages/count_tokens.md +++ b/content/en/api/ruby/messages/count_tokens.md @@ -2295,15 +2295,19 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -3758,7 +3762,10 @@ require "anthropic" anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") -message_tokens_count = anthropic.messages.count_tokens(messages: [{content: "string", role: :user}], model: :"claude-opus-4-6") +message_tokens_count = anthropic.messages.count_tokens( + messages: [{content: "string", role: :user}], + model: :"claude-mythos-preview" +) puts(message_tokens_count) ``` diff --git a/content/en/api/ruby/messages/create.md b/content/en/api/ruby/messages/create.md index 4ac905929..5af1243e7 100644 --- a/content/en/api/ruby/messages/create.md +++ b/content/en/api/ruby/messages/create.md @@ -2303,15 +2303,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` @@ -4530,15 +4534,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `:"claude-opus-4-6" | :"claude-sonnet-4-6" | :"claude-haiku-4-5" | 12 more` + - `:"claude-mythos-preview" | :"claude-opus-4-6" | :"claude-sonnet-4-6" | 13 more` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + - `:"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + - `:"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `:"claude-sonnet-4-6"` diff --git a/content/en/api/ruby/models.md b/content/en/api/ruby/models.md index cce4b7d15..07955dccb 100644 --- a/content/en/api/ruby/models.md +++ b/content/en/api/ruby/models.md @@ -32,7 +32,7 @@ The Models API response can be used to determine which models are available for - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -76,8 +76,6 @@ The Models API response can be used to determine which models are available for - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class ModelInfo` @@ -296,7 +294,7 @@ The Models API response can be used to determine information about a specific mo - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -340,8 +338,6 @@ The Models API response can be used to determine information about a specific mo - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class ModelInfo` diff --git a/content/en/api/ruby/models/list.md b/content/en/api/ruby/models/list.md index e8562a007..3803cce3d 100644 --- a/content/en/api/ruby/models/list.md +++ b/content/en/api/ruby/models/list.md @@ -30,7 +30,7 @@ The Models API response can be used to determine which models are available for - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ The Models API response can be used to determine which models are available for - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class ModelInfo` diff --git a/content/en/api/ruby/models/retrieve.md b/content/en/api/ruby/models/retrieve.md index f0ed7a6cf..8ed0bb9ce 100644 --- a/content/en/api/ruby/models/retrieve.md +++ b/content/en/api/ruby/models/retrieve.md @@ -20,7 +20,7 @@ The Models API response can be used to determine information about a specific mo - `String` - - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 19 more` + - `:"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 18 more` - `:"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ The Models API response can be used to determine information about a specific mo - `:"output-300k-2026-03-24"` - - `:"user-profiles-2026-03-24"` - ### Returns - `class ModelInfo` diff --git a/content/en/api/sdks/cli.md b/content/en/api/sdks/cli.md new file mode 100644 index 000000000..19800a0aa --- /dev/null +++ b/content/en/api/sdks/cli.md @@ -0,0 +1,542 @@ +# CLI + +Interact with the Claude API directly from your terminal with the ant command-line tool + +--- + +The `ant` CLI provides access to the Claude API from your terminal. Every API resource is exposed as a subcommand, with output formatting, response filtering, and support for YAML or JSON file input that make it practical for both interactive exploration and automation. + +Compared to calling the API with `curl`, `ant` lets you build request bodies from typed flags or piped YAML rather than hand-written JSON, inline file contents into string fields with an `@path` reference, and extract fields from the response with a built-in `--transform` query — no separate JSON tooling required. List endpoints paginate automatically. Claude Code understands how to use `ant` natively. + + +For endpoint-specific parameters and response schemas, see the [API reference](/docs/en/api/cli/messages/create). This page covers CLI-specific features and workflows that apply across all endpoints. + + +## Installation + + + + +```bash +brew install anthropics/tap/ant +``` + +On macOS, unquarantine the binary: + +```bash +xattr -d com.apple.quarantine "$(brew --prefix)/bin/ant" +``` + + + + +For Linux environments, download the release binary directly. + +```bash +VERSION=1.0.0 +OS=$(uname -s | tr '[:upper:]' '[:lower:]') +ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/') +curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \ + | sudo tar -xz -C /usr/local/bin ant +``` + +You can find all releases on the [GitHub releases page](https://github.com/anthropics/anthropic-cli/releases). + + + + +You may also install the CLI from source using `go install`. Requires Go 1.22 or later. + +```bash +go install github.com/anthropics/anthropic-cli/cmd/ant@latest +``` + +The binary is placed in `$(go env GOPATH)/bin`. Add it to your `PATH` if it isn't already: + +```bash +export PATH="$PATH:$(go env GOPATH)/bin" +``` + + + + +Check the installation: + +```bash +ant --version +``` + +## Authentication + +The CLI reads your API key from the `ANTHROPIC_API_KEY` environment variable. + + + + +```bash +echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.zshrc +source ~/.zshrc +``` + + + + +```bash +echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.bashrc +source ~/.bashrc +``` + + + + +```powershell +setx ANTHROPIC_API_KEY "sk-ant-api03-..." +``` + +Open a new terminal for the change to take effect. + + + + +Get a key from the [Claude Console](https://platform.claude.com/settings/keys). To point at a different API host, set `ANTHROPIC_BASE_URL` or pass `--base-url` on any command. + +## Send your first request + +With the binary installed and `ANTHROPIC_API_KEY` set, call the [Messages API](/docs/en/api/cli/messages/create): + +```bash +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --message '{role: user, content: "Hello, Claude"}' +``` + +```json Output +{ + "model": "claude-opus-4-6", + "id": "msg_01YMmR5XodC5nTqMxLZMKaq6", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "Hello! How are you doing today? Is there something I can help you with?" + } + ], + "stop_reason": "end_turn", + "usage": { "input_tokens": 27, "output_tokens": 20 /*, ... */ } +} +``` + +The response is the full API object, pretty-printed because stdout is a terminal. The rest of this page covers how to reshape that output, pass complex request bodies, and chain commands together. + +## Command structure + +Commands follow a `resource action` pattern. Nested resources use colons: + +```text +ant [:] [flags] +``` + +Run `ant --help` for the full resource list, or append `--help` to any subcommand for its flags. + +Resources currently in beta — including agents, sessions, deployments, environments, and skills — live under the `beta:` prefix. Commands in this namespace automatically send the appropriate `anthropic-beta` header for that resource, so you don't need to pass it yourself. Use `--beta
                                                                                                                                                                                                                                                                                                                                                                                    ` only to override the default — for example, to opt into a different schema version. + +```bash +ant models list +ant messages create --model claude-opus-4-6 --max-tokens 1024 ... +ant beta:agents retrieve --agent-id agent_01... +ant beta:sessions:events list --session-id session_01... +``` + +### Global flags + +| Flag | Description | +| --- | --- | +| `--format` | Output format: `auto`, `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore` | +| `--transform` | Filter or reshape the response with a [GJSON path](#transform-output-with-gjson) | +| `--base-url` | Override the API base URL | +| `--debug` | Print full HTTP request and response to stderr | +| `--format-error`, `--transform-error` | Same as `--format` and `--transform` but applied to [error responses](#inspect-errors) | + +## Output formats + +The default `auto` format pretty-prints JSON when writing to a terminal and emits compact JSON when piped. Override it with `--format`: + +```bash +ant models retrieve --model-id claude-opus-4-6 --format yaml +``` + +```yaml Output +type: model +id: claude-opus-4-6 +display_name: Claude Opus 4.6 +created_at: "2026-02-04T00:00:00Z" +... +``` + +List endpoints auto-paginate. In the default formats each item is written separately (one compact JSON object per line in `jsonl` mode, a stream of YAML documents in `yaml` mode), which streams cleanly into `head`, `grep`, and `--transform` filters. + +### Interactive explorer + +When connected to a terminal, `--format explore` opens a fold-and-search TUI for browsing large responses. Arrow keys expand and collapse nodes, `/` searches, `q` exits. + +```bash +ant models list --format explore +``` + +## Transform output with GJSON + +Use `--transform` to reshape responses before printing. The expression is a [GJSON path](https://github.com/tidwall/gjson/blob/master/SYNTAX.md). For list endpoints the transform runs against each item individually, not the envelope: + +```bash +ant beta:agents list \ + --transform "{id,name,model}" \ + --format jsonl +``` + +```jsonl Output +{"id": "agent_011CYm1BLqPX...", "name": "Docs CLI Test Agent", "model": "claude-sonnet-4-6"} +{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-sonnet-4-6"} +{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-4-5"} +``` + +### Extract a scalar + +To capture a single field as an unquoted string — for example, the ID of a newly created resource — pair `--transform` with `--format yaml`. YAML emits scalar values without quotes, so the result is ready to assign to a shell variable: + +```bash +AGENT_ID=$(ant beta:agents create \ + --name "My Agent" \ + --model claude-sonnet-4-6 \ + --transform id --format yaml) + +printf '%s\n' "$AGENT_ID" +``` + +```text Output +agent_011CYm1BLqPXpQRk5khsSXrs +``` + + +`--transform` is not applied when `--format raw` is set. Use `--format yaml` for unquoted scalars, or `--format jsonl` to keep the result as structured data for further processing. + + +## Passing request bodies + +The right input mechanism depends on the shape of the data: use **flags** for scalar fields and short structured values, pipe a **stdin** document for nested or multi-line bodies, and use **`@file` references** to pull file contents into any string or binary field. + +### Flags + +Scalar fields map directly to flags. Structured fields accept a relaxed YAML-like syntax (unquoted keys, optional quotes around strings) or strict JSON: + +```bash +ant beta:sessions create \ + --agent '{type: agent, id: agent_011CYm1BLqPXpQRk5khsSXrs, version: 1}' \ + --environment env_01595EKxaaTTGwwY3kyXdtbs \ + --title "CLI docs test session" +``` + +Repeatable flags build arrays. Each `--tool` or `--event` appends one element: + +```bash +ant beta:agents create \ + --name "Research Agent" \ + --model claude-opus-4-6 \ + --tool '{type: agent_toolset_20260401}' \ + --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}' +``` + +### Stdin + +Pipe a JSON or YAML document to stdin to supply the full request body. Fields from stdin are merged with flags, with flags taking precedence. Here `version` is the optimistic-locking token returned by an earlier `retrieve`, and `$AGENT_ID` was captured as in [Extract a scalar](#extract-a-scalar): + +```bash +echo '{"description": "Updated test agent.", "version": 1}' | \ + ant beta:agents update --agent-id "$AGENT_ID" +``` + +Heredocs work the same way and are convenient for multi-line YAML. Quote the delimiter (as in `<<'YAML'`) to disable variable expansion inside the body. + +```bash +ant beta:agents create <<'YAML' +name: Research Agent +model: claude-opus-4-6 +system: | + You are a research assistant. Cite sources for every claim. +tools: + - type: agent_toolset_20260401 +YAML +``` + +### File references + +Flags that take a file path, such as `--file` on the upload command, accept a bare path: + +```bash +ant beta:files upload --file ./report.pdf +``` + +To inline a file's contents into a string-valued field, prefix the path with `@`: + +```bash +ant beta:agents create \ + --name "Researcher" --model claude-sonnet-4-6 \ + --system @./prompts/researcher.txt +``` + +Inside structured flag values, wrap the path in quotes. To send a PDF to the Messages API: + +```bash +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --message '{role: user, content: [ + {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}}, + {type: text, text: "Extract the text from this scanned document."} + ]}' \ + --transform 'content.0.text' --format yaml +``` + +The CLI detects the file type and encodes binary files as base64 automatically. To force a specific encoding use `@file://` for plain text or `@data://` for base64. Escape a literal leading `@` with a backslash (`\@username`). + +## Version-controlling API resources + +You can use the CLI to version control API resources such as skills, agents, environments, or deployments as YAML files in your repository and keep them in sync with the Claude API. + + +For more information on these resources, see [Managed Agents](/docs/en/managed-agents/overview). + + + + + +Write the agent definition to `summarizer.agent.yaml`: + +```yaml summarizer.agent.yaml +name: Summarizer +model: claude-sonnet-4-6 +system: | + You are a helpful assistant that writes concise summaries. +tools: + - type: agent_toolset_20260401 +``` + + + + +```bash +ant beta:agents create < summarizer.agent.yaml +``` + +```json Output +{ + "id": "agent_011CYm1BLqPXpQRk5khsSXrs", + "version": 1, + "name": "Summarizer", + "model": "claude-sonnet-4-6" + /* ... */ +} +``` + +Note the `id` from the response — you'll pass it to the session create command below. + + +Check `summarizer.agent.yaml` into your repository and keep it in sync with the API in your CI pipeline. The update command needs the agent ID and current version as flags: + +```bash CLI +ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml +``` + + + + + +A session runs in an [environment](/docs/en/api/cli/beta/environments), which defines the container it executes in. Write the environment definition to `summarizer.environment.yaml`: + +```yaml summarizer.environment.yaml +name: summarizer-env +config: + type: cloud + networking: + type: unrestricted +``` + + + + +```bash +ant beta:environments create < summarizer.environment.yaml +``` + +```json Output +{ + "id": "env_01595EKxaaTTGwwY3kyXdtbs", + "name": "summarizer-env" + /* ... */ +} +``` + +Note the `id` from the response — you'll pass it to the session create command below. + + +Check `summarizer.environment.yaml` into your repository and keep it in sync with the API in your CI pipeline. The update command needs the environment ID as a flag: + +```bash CLI +ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml +``` + + + + + +Paste the agent `id` and environment `id` from the previous outputs into the session create command: + +```bash highlight={2..3} +ant beta:sessions create \ + --agent agent_011CYm1BLqPXpQRk5khsSXrs \ + --environment env_01595EKxaaTTGwwY3kyXdtbs \ + --title "Summarization task" +``` + +```json Output +{ + "id": "session_01JZCh78XvmxJjiXVy3oSi7K", + "status": "running" + /* ... */ +} +``` + + + + +Copy the session `id` from the previous output into `--session-id`: + +```bash highlight={2} +ant beta:sessions:events send \ + --session-id session_01JZCh78XvmxJjiXVy3oSi7K \ + --event '{type: user.message, content: [{type: text, text: "Summarize the benefits of type safety in one sentence."}]}' +``` + + + + +`--transform` runs against each listed event, so this prints the text of every message in order: + +```bash highlight={2} +ant beta:sessions:events list \ + --session-id session_01JZCh78XvmxJjiXVy3oSi7K \ + --transform 'content.0.text' --format yaml +``` + +```text Output +Summarize the benefits of type safety in one sentence. +Type safety catches errors at compile time rather than runtime, reducing bugs, improving code clarity, enabling better tooling support, and making codebases easier to maintain and refactor with confidence. +``` + + +To watch a session as it runs, use `ant beta:sessions stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K`. Events are written to stdout as they arrive. + + + + + +## Scripting patterns + +The CLI is designed to compose with standard shell tooling. + +### Chain list output into a second command + +`--transform id --format yaml` on a list endpoint emits one bare ID per line, so standard tools such as `head` and `xargs` apply directly. Capture the first result, then pass it to a follow-up command: + +```bash +FIRST_AGENT=$(ant beta:agents list \ + --transform id --format yaml | head -1) + +ant beta:agents:versions list \ + --agent-id "$FIRST_AGENT" \ + --transform "{version,created_at}" --format jsonl +``` + +### Inspect errors + +The `--transform-error` and `--format-error` flags mirror their success-path counterparts and follow the same rule — pair with `yaml`, not `raw`, to apply the transform. Extract only the error message: + +```bash +ant beta:agents retrieve --agent-id bogus \ + --transform-error error.message --format-error yaml 2>&1 +``` + +```text Output +GET "https://api.anthropic.com/v1/agents/bogus?beta=true": 404 Not Found +Agent not found. +``` + +## Use the CLI from Claude Code + +[Claude Code](https://docs.claude.com/en/docs/claude-code/overview) knows out of the box how to use the `ant` CLI. With the CLI installed and `ANTHROPIC_API_KEY` set, you can ask Claude Code to operate on your API resources directly — for example: + +- "List my recent agent sessions and summarize which ones errored." +- "Upload every PDF in `./reports` to the Files API and print the resulting IDs." +- "Pull the events for session `session_01...` and tell me where the agent got stuck." + +Claude Code shells out to `ant`, parses the structured output, and reasons over the results — no custom integration code required. + +## Debugging + +Add `--debug` to any command to print the exact HTTP request and response (headers and body) to stderr. API keys are redacted. + +```bash +ant --debug beta:agents list +``` + +```text Output +GET /v1/agents?beta=true HTTP/1.1 +Host: api.anthropic.com +Anthropic-Beta: managed-agents-2026-04-01 +Anthropic-Version: 2023-06-01 +X-Api-Key: +... +``` + +## Shell completion + +The CLI ships completion scripts for bash, zsh, fish, and PowerShell. Generate and install one for your shell: + + + + +```bash +ant @completion zsh > "${fpath[1]}/_ant" +# Restart your shell or run: autoload -U compinit && compinit +``` + + + + +```bash +ant @completion bash > /etc/bash_completion.d/ant +``` + + + + +```bash +ant @completion fish > ~/.config/fish/completions/ant.fish +``` + + + + +```powershell +ant @completion powershell | Out-String | Invoke-Expression +# To persist across sessions: +# ant @completion powershell >> $PROFILE +``` + + + + +## Available resources + +Every API resource the CLI exposes is documented in the [API reference](/docs/en/api/cli/messages/create). For a local listing, run `ant --help`, and append `--help` to any subcommand for its flags and parameters. \ No newline at end of file diff --git a/content/en/api/sdks/java.md b/content/en/api/sdks/java.md index cc4de6f9b..0e70456dc 100644 --- a/content/en/api/sdks/java.md +++ b/content/en/api/sdks/java.md @@ -15,7 +15,7 @@ For API feature documentation with code examples, see the [API reference](/docs/ ```kotlin -implementation("com.anthropic:anthropic-java:2.18.0") +implementation("com.anthropic:anthropic-java:2.20.0") ``` @@ -23,7 +23,7 @@ implementation("com.anthropic:anthropic-java:2.18.0") com.anthropic anthropic-java - 2.18.0 + 2.20.0 ``` diff --git a/content/en/api/sdks/ruby.md b/content/en/api/sdks/ruby.md index cb799e7ce..c3d27a76a 100644 --- a/content/en/api/sdks/ruby.md +++ b/content/en/api/sdks/ruby.md @@ -12,10 +12,10 @@ For API feature documentation with code examples, see the [API reference](/docs/ ## Installation -To use this gem, install via Bundler by adding the following to your application's `Gemfile`: +Add the gem to your application's `Gemfile` with Bundler: -```ruby -gem "anthropic", "~> 1.25.0" +```bash +bundle add anthropic ``` ## Requirements diff --git a/content/en/api/service-tiers.md b/content/en/api/service-tiers.md index 5b145059e..9ee1512f4 100644 --- a/content/en/api/service-tiers.md +++ b/content/en/api/service-tiers.md @@ -53,7 +53,7 @@ If servicing the request would exceed the rate limits, the request is declined. You can control which service tiers can be used for a request by setting the `service_tier` parameter: -```python +```python Python message = client.messages.create( model="claude-opus-4-6", max_tokens=1024, diff --git a/content/en/api/terraform/beta.md b/content/en/api/terraform/beta.md index dc93e3831..0ee8d807a 100644 --- a/content/en/api/terraform/beta.md +++ b/content/en/api/terraform/beta.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/terraform/beta/agents.md b/content/en/api/terraform/beta/agents.md new file mode 100644 index 000000000..dd265a26c --- /dev/null +++ b/content/en/api/terraform/beta/agents.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/terraform/beta/agents/archive.md b/content/en/api/terraform/beta/agents/archive.md new file mode 100644 index 000000000..1ca0ad0f3 --- /dev/null +++ b/content/en/api/terraform/beta/agents/archive.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/terraform/beta/agents/create.md b/content/en/api/terraform/beta/agents/create.md new file mode 100644 index 000000000..d36f3f031 --- /dev/null +++ b/content/en/api/terraform/beta/agents/create.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/terraform/beta/agents/list.md b/content/en/api/terraform/beta/agents/list.md new file mode 100644 index 000000000..97211df89 --- /dev/null +++ b/content/en/api/terraform/beta/agents/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/terraform/beta/agents/retrieve.md b/content/en/api/terraform/beta/agents/retrieve.md new file mode 100644 index 000000000..9356ea517 --- /dev/null +++ b/content/en/api/terraform/beta/agents/retrieve.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/terraform/beta/agents/update.md b/content/en/api/terraform/beta/agents/update.md new file mode 100644 index 000000000..dddf6d23b --- /dev/null +++ b/content/en/api/terraform/beta/agents/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/terraform/beta/agents/versions.md b/content/en/api/terraform/beta/agents/versions.md new file mode 100644 index 000000000..f59f98d6c --- /dev/null +++ b/content/en/api/terraform/beta/agents/versions.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/terraform/beta/agents/versions/list.md b/content/en/api/terraform/beta/agents/versions/list.md new file mode 100644 index 000000000..37c0f7cac --- /dev/null +++ b/content/en/api/terraform/beta/agents/versions/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/terraform/beta/environments.md b/content/en/api/terraform/beta/environments.md new file mode 100644 index 000000000..10a85e602 --- /dev/null +++ b/content/en/api/terraform/beta/environments.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/terraform/beta/environments/archive.md b/content/en/api/terraform/beta/environments/archive.md new file mode 100644 index 000000000..50fc48010 --- /dev/null +++ b/content/en/api/terraform/beta/environments/archive.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/terraform/beta/environments/create.md b/content/en/api/terraform/beta/environments/create.md new file mode 100644 index 000000000..c64eb6656 --- /dev/null +++ b/content/en/api/terraform/beta/environments/create.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/terraform/beta/environments/delete.md b/content/en/api/terraform/beta/environments/delete.md new file mode 100644 index 000000000..12ea41c19 --- /dev/null +++ b/content/en/api/terraform/beta/environments/delete.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/terraform/beta/environments/list.md b/content/en/api/terraform/beta/environments/list.md new file mode 100644 index 000000000..b3039d549 --- /dev/null +++ b/content/en/api/terraform/beta/environments/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/terraform/beta/environments/retrieve.md b/content/en/api/terraform/beta/environments/retrieve.md new file mode 100644 index 000000000..b8452a47c --- /dev/null +++ b/content/en/api/terraform/beta/environments/retrieve.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/terraform/beta/environments/update.md b/content/en/api/terraform/beta/environments/update.md new file mode 100644 index 000000000..2c3cff59f --- /dev/null +++ b/content/en/api/terraform/beta/environments/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/terraform/beta/files.md b/content/en/api/terraform/beta/files.md index 6f670025d..83582bf5c 100644 --- a/content/en/api/terraform/beta/files.md +++ b/content/en/api/terraform/beta/files.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/terraform/beta/files/delete.md b/content/en/api/terraform/beta/files/delete.md index 828a357cf..45e8ed982 100644 --- a/content/en/api/terraform/beta/files/delete.md +++ b/content/en/api/terraform/beta/files/delete.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/terraform/beta/files/download.md b/content/en/api/terraform/beta/files/download.md index 9f88e1acb..9eaaa0618 100644 --- a/content/en/api/terraform/beta/files/download.md +++ b/content/en/api/terraform/beta/files/download.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/terraform/beta/files/list.md b/content/en/api/terraform/beta/files/list.md index c821b45eb..3e6e01ede 100644 --- a/content/en/api/terraform/beta/files/list.md +++ b/content/en/api/terraform/beta/files/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/terraform/beta/files/retrieve_metadata.md b/content/en/api/terraform/beta/files/retrieve_metadata.md index 57fe64f4c..2f904f381 100644 --- a/content/en/api/terraform/beta/files/retrieve_metadata.md +++ b/content/en/api/terraform/beta/files/retrieve_metadata.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/terraform/beta/files/upload.md b/content/en/api/terraform/beta/files/upload.md index d9c28f0f0..3033bff65 100644 --- a/content/en/api/terraform/beta/files/upload.md +++ b/content/en/api/terraform/beta/files/upload.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/terraform/beta/messages.md b/content/en/api/terraform/beta/messages.md index 6902e46bd..458ee6037 100644 --- a/content/en/api/terraform/beta/messages.md +++ b/content/en/api/terraform/beta/messages.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/terraform/beta/messages/batches.md b/content/en/api/terraform/beta/messages/batches.md index ad657b4da..6df0d10b6 100644 --- a/content/en/api/terraform/beta/messages/batches.md +++ b/content/en/api/terraform/beta/messages/batches.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/terraform/beta/messages/batches/cancel.md b/content/en/api/terraform/beta/messages/batches/cancel.md index 2ad9c1872..8db2b9382 100644 --- a/content/en/api/terraform/beta/messages/batches/cancel.md +++ b/content/en/api/terraform/beta/messages/batches/cancel.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/terraform/beta/messages/batches/create.md b/content/en/api/terraform/beta/messages/batches/create.md index 1286fdd98..75058ad02 100644 --- a/content/en/api/terraform/beta/messages/batches/create.md +++ b/content/en/api/terraform/beta/messages/batches/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/terraform/beta/messages/batches/delete.md b/content/en/api/terraform/beta/messages/batches/delete.md index 2a95a4297..98e7cc5e5 100644 --- a/content/en/api/terraform/beta/messages/batches/delete.md +++ b/content/en/api/terraform/beta/messages/batches/delete.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/terraform/beta/messages/batches/list.md b/content/en/api/terraform/beta/messages/batches/list.md index 3b3895a2b..ff538d6b6 100644 --- a/content/en/api/terraform/beta/messages/batches/list.md +++ b/content/en/api/terraform/beta/messages/batches/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/terraform/beta/messages/batches/results.md b/content/en/api/terraform/beta/messages/batches/results.md index e8174026f..40d58c019 100644 --- a/content/en/api/terraform/beta/messages/batches/results.md +++ b/content/en/api/terraform/beta/messages/batches/results.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/terraform/beta/messages/batches/retrieve.md b/content/en/api/terraform/beta/messages/batches/retrieve.md index 9dd920090..78cc8645f 100644 --- a/content/en/api/terraform/beta/messages/batches/retrieve.md +++ b/content/en/api/terraform/beta/messages/batches/retrieve.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/terraform/beta/messages/count_tokens.md b/content/en/api/terraform/beta/messages/count_tokens.md index bafa06e21..6531d1b8f 100644 --- a/content/en/api/terraform/beta/messages/count_tokens.md +++ b/content/en/api/terraform/beta/messages/count_tokens.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/terraform/beta/messages/create.md b/content/en/api/terraform/beta/messages/create.md index e385e4aaf..3402716a3 100644 --- a/content/en/api/terraform/beta/messages/create.md +++ b/content/en/api/terraform/beta/messages/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/terraform/beta/models.md b/content/en/api/terraform/beta/models.md index 48a083e9e..d8fa78b91 100644 --- a/content/en/api/terraform/beta/models.md +++ b/content/en/api/terraform/beta/models.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/terraform/beta/models/list.md b/content/en/api/terraform/beta/models/list.md index 526e53467..69e2d7c7c 100644 --- a/content/en/api/terraform/beta/models/list.md +++ b/content/en/api/terraform/beta/models/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/terraform/beta/models/retrieve.md b/content/en/api/terraform/beta/models/retrieve.md index 0ae2c7a88..f214b8d62 100644 --- a/content/en/api/terraform/beta/models/retrieve.md +++ b/content/en/api/terraform/beta/models/retrieve.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions.md b/content/en/api/terraform/beta/sessions.md new file mode 100644 index 000000000..eed28d75e --- /dev/null +++ b/content/en/api/terraform/beta/sessions.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/archive.md b/content/en/api/terraform/beta/sessions/archive.md new file mode 100644 index 000000000..b57d441ce --- /dev/null +++ b/content/en/api/terraform/beta/sessions/archive.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/create.md b/content/en/api/terraform/beta/sessions/create.md new file mode 100644 index 000000000..bab1d202d --- /dev/null +++ b/content/en/api/terraform/beta/sessions/create.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/delete.md b/content/en/api/terraform/beta/sessions/delete.md new file mode 100644 index 000000000..4aa084162 --- /dev/null +++ b/content/en/api/terraform/beta/sessions/delete.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/events.md b/content/en/api/terraform/beta/sessions/events.md new file mode 100644 index 000000000..42b19d274 --- /dev/null +++ b/content/en/api/terraform/beta/sessions/events.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/events/list.md b/content/en/api/terraform/beta/sessions/events/list.md new file mode 100644 index 000000000..42e00f675 --- /dev/null +++ b/content/en/api/terraform/beta/sessions/events/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/events/send.md b/content/en/api/terraform/beta/sessions/events/send.md new file mode 100644 index 000000000..82f6a8b67 --- /dev/null +++ b/content/en/api/terraform/beta/sessions/events/send.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/events/stream.md b/content/en/api/terraform/beta/sessions/events/stream.md new file mode 100644 index 000000000..78fa425a8 --- /dev/null +++ b/content/en/api/terraform/beta/sessions/events/stream.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/list.md b/content/en/api/terraform/beta/sessions/list.md new file mode 100644 index 000000000..5f619ae39 --- /dev/null +++ b/content/en/api/terraform/beta/sessions/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/resources.md b/content/en/api/terraform/beta/sessions/resources.md new file mode 100644 index 000000000..648d39ba2 --- /dev/null +++ b/content/en/api/terraform/beta/sessions/resources.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/resources/add.md b/content/en/api/terraform/beta/sessions/resources/add.md new file mode 100644 index 000000000..d0bda7a29 --- /dev/null +++ b/content/en/api/terraform/beta/sessions/resources/add.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/resources/delete.md b/content/en/api/terraform/beta/sessions/resources/delete.md new file mode 100644 index 000000000..8ebe5800e --- /dev/null +++ b/content/en/api/terraform/beta/sessions/resources/delete.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/resources/list.md b/content/en/api/terraform/beta/sessions/resources/list.md new file mode 100644 index 000000000..9d0ad2764 --- /dev/null +++ b/content/en/api/terraform/beta/sessions/resources/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/resources/retrieve.md b/content/en/api/terraform/beta/sessions/resources/retrieve.md new file mode 100644 index 000000000..2e04d70b0 --- /dev/null +++ b/content/en/api/terraform/beta/sessions/resources/retrieve.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/resources/update.md b/content/en/api/terraform/beta/sessions/resources/update.md new file mode 100644 index 000000000..a9747b964 --- /dev/null +++ b/content/en/api/terraform/beta/sessions/resources/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/retrieve.md b/content/en/api/terraform/beta/sessions/retrieve.md new file mode 100644 index 000000000..3c704d141 --- /dev/null +++ b/content/en/api/terraform/beta/sessions/retrieve.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/terraform/beta/sessions/update.md b/content/en/api/terraform/beta/sessions/update.md new file mode 100644 index 000000000..57c1ba61a --- /dev/null +++ b/content/en/api/terraform/beta/sessions/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/terraform/beta/skills.md b/content/en/api/terraform/beta/skills.md index 18d83ef6a..e005a50f0 100644 --- a/content/en/api/terraform/beta/skills.md +++ b/content/en/api/terraform/beta/skills.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/terraform/beta/skills/create.md b/content/en/api/terraform/beta/skills/create.md index 3bbd6e565..ddcf50c3a 100644 --- a/content/en/api/terraform/beta/skills/create.md +++ b/content/en/api/terraform/beta/skills/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/terraform/beta/skills/delete.md b/content/en/api/terraform/beta/skills/delete.md index 633194019..777491d07 100644 --- a/content/en/api/terraform/beta/skills/delete.md +++ b/content/en/api/terraform/beta/skills/delete.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/terraform/beta/skills/list.md b/content/en/api/terraform/beta/skills/list.md index 07f0c50e5..d5971430d 100644 --- a/content/en/api/terraform/beta/skills/list.md +++ b/content/en/api/terraform/beta/skills/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/terraform/beta/skills/retrieve.md b/content/en/api/terraform/beta/skills/retrieve.md index 18e0a5770..3b19fca5f 100644 --- a/content/en/api/terraform/beta/skills/retrieve.md +++ b/content/en/api/terraform/beta/skills/retrieve.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/terraform/beta/skills/versions.md b/content/en/api/terraform/beta/skills/versions.md index 62555094f..9e69a23b8 100644 --- a/content/en/api/terraform/beta/skills/versions.md +++ b/content/en/api/terraform/beta/skills/versions.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/terraform/beta/skills/versions/create.md b/content/en/api/terraform/beta/skills/versions/create.md index 731164857..ba8607298 100644 --- a/content/en/api/terraform/beta/skills/versions/create.md +++ b/content/en/api/terraform/beta/skills/versions/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/terraform/beta/skills/versions/delete.md b/content/en/api/terraform/beta/skills/versions/delete.md index bbab78072..29e265b24 100644 --- a/content/en/api/terraform/beta/skills/versions/delete.md +++ b/content/en/api/terraform/beta/skills/versions/delete.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/terraform/beta/skills/versions/list.md b/content/en/api/terraform/beta/skills/versions/list.md index 1d81a3ec7..ba6771594 100644 --- a/content/en/api/terraform/beta/skills/versions/list.md +++ b/content/en/api/terraform/beta/skills/versions/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/terraform/beta/skills/versions/retrieve.md b/content/en/api/terraform/beta/skills/versions/retrieve.md index 09d2bc8c0..c5c73a967 100644 --- a/content/en/api/terraform/beta/skills/versions/retrieve.md +++ b/content/en/api/terraform/beta/skills/versions/retrieve.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults.md b/content/en/api/terraform/beta/vaults.md new file mode 100644 index 000000000..c3af4b62e --- /dev/null +++ b/content/en/api/terraform/beta/vaults.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/archive.md b/content/en/api/terraform/beta/vaults/archive.md new file mode 100644 index 000000000..07686a399 --- /dev/null +++ b/content/en/api/terraform/beta/vaults/archive.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/create.md b/content/en/api/terraform/beta/vaults/create.md new file mode 100644 index 000000000..ba181445b --- /dev/null +++ b/content/en/api/terraform/beta/vaults/create.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/credentials.md b/content/en/api/terraform/beta/vaults/credentials.md new file mode 100644 index 000000000..b8e44ed5d --- /dev/null +++ b/content/en/api/terraform/beta/vaults/credentials.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/credentials/archive.md b/content/en/api/terraform/beta/vaults/credentials/archive.md new file mode 100644 index 000000000..855ca5c85 --- /dev/null +++ b/content/en/api/terraform/beta/vaults/credentials/archive.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/credentials/create.md b/content/en/api/terraform/beta/vaults/credentials/create.md new file mode 100644 index 000000000..4e2de041e --- /dev/null +++ b/content/en/api/terraform/beta/vaults/credentials/create.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/credentials/delete.md b/content/en/api/terraform/beta/vaults/credentials/delete.md new file mode 100644 index 000000000..c0e18b2ae --- /dev/null +++ b/content/en/api/terraform/beta/vaults/credentials/delete.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/credentials/list.md b/content/en/api/terraform/beta/vaults/credentials/list.md new file mode 100644 index 000000000..3ef1995b7 --- /dev/null +++ b/content/en/api/terraform/beta/vaults/credentials/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/credentials/retrieve.md b/content/en/api/terraform/beta/vaults/credentials/retrieve.md new file mode 100644 index 000000000..e9c434ad9 --- /dev/null +++ b/content/en/api/terraform/beta/vaults/credentials/retrieve.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/credentials/update.md b/content/en/api/terraform/beta/vaults/credentials/update.md new file mode 100644 index 000000000..066a323c7 --- /dev/null +++ b/content/en/api/terraform/beta/vaults/credentials/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/delete.md b/content/en/api/terraform/beta/vaults/delete.md new file mode 100644 index 000000000..ab39eec78 --- /dev/null +++ b/content/en/api/terraform/beta/vaults/delete.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/list.md b/content/en/api/terraform/beta/vaults/list.md new file mode 100644 index 000000000..a991648fb --- /dev/null +++ b/content/en/api/terraform/beta/vaults/list.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/retrieve.md b/content/en/api/terraform/beta/vaults/retrieve.md new file mode 100644 index 000000000..bcd2e4c02 --- /dev/null +++ b/content/en/api/terraform/beta/vaults/retrieve.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file diff --git a/content/en/api/terraform/beta/vaults/update.md b/content/en/api/terraform/beta/vaults/update.md new file mode 100644 index 000000000..0e9c60178 --- /dev/null +++ b/content/en/api/terraform/beta/vaults/update.md @@ -0,0 +1 @@ +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/terraform/completions.md b/content/en/api/terraform/completions.md index 6f06c6359..597cb8436 100644 --- a/content/en/api/terraform/completions.md +++ b/content/en/api/terraform/completions.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/terraform/completions/create.md b/content/en/api/terraform/completions/create.md index 078ba5ada..ce8a7117b 100644 --- a/content/en/api/terraform/completions/create.md +++ b/content/en/api/terraform/completions/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/terraform/messages.md b/content/en/api/terraform/messages.md index ecd84a91f..b32c29908 100644 --- a/content/en/api/terraform/messages.md +++ b/content/en/api/terraform/messages.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/terraform/messages/batches.md b/content/en/api/terraform/messages/batches.md index 42e147bc3..0282dfd95 100644 --- a/content/en/api/terraform/messages/batches.md +++ b/content/en/api/terraform/messages/batches.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/terraform/messages/batches/cancel.md b/content/en/api/terraform/messages/batches/cancel.md index 7ccb7491d..5ac8f9dda 100644 --- a/content/en/api/terraform/messages/batches/cancel.md +++ b/content/en/api/terraform/messages/batches/cancel.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/terraform/messages/batches/create.md b/content/en/api/terraform/messages/batches/create.md index 3ee6e46c1..cb5608633 100644 --- a/content/en/api/terraform/messages/batches/create.md +++ b/content/en/api/terraform/messages/batches/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/terraform/messages/batches/delete.md b/content/en/api/terraform/messages/batches/delete.md index 0043cad98..f6e3d84d0 100644 --- a/content/en/api/terraform/messages/batches/delete.md +++ b/content/en/api/terraform/messages/batches/delete.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/terraform/messages/batches/list.md b/content/en/api/terraform/messages/batches/list.md index 541f3ce93..538f6e225 100644 --- a/content/en/api/terraform/messages/batches/list.md +++ b/content/en/api/terraform/messages/batches/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/terraform/messages/batches/results.md b/content/en/api/terraform/messages/batches/results.md index 2d4e934d7..9e7bd0d3e 100644 --- a/content/en/api/terraform/messages/batches/results.md +++ b/content/en/api/terraform/messages/batches/results.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/terraform/messages/batches/retrieve.md b/content/en/api/terraform/messages/batches/retrieve.md index f519fef79..50a412812 100644 --- a/content/en/api/terraform/messages/batches/retrieve.md +++ b/content/en/api/terraform/messages/batches/retrieve.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/terraform/messages/count_tokens.md b/content/en/api/terraform/messages/count_tokens.md index a8d4d39f7..823b5ff87 100644 --- a/content/en/api/terraform/messages/count_tokens.md +++ b/content/en/api/terraform/messages/count_tokens.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/terraform/messages/create.md b/content/en/api/terraform/messages/create.md index 19ca14a24..60a112c95 100644 --- a/content/en/api/terraform/messages/create.md +++ b/content/en/api/terraform/messages/create.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        \ No newline at end of file diff --git a/content/en/api/terraform/models.md b/content/en/api/terraform/models.md index 0bbc3c8fb..506def2e5 100644 --- a/content/en/api/terraform/models.md +++ b/content/en/api/terraform/models.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            \ No newline at end of file diff --git a/content/en/api/terraform/models/list.md b/content/en/api/terraform/models/list.md index b9dc440e0..6127f31a4 100644 --- a/content/en/api/terraform/models/list.md +++ b/content/en/api/terraform/models/list.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                \ No newline at end of file diff --git a/content/en/api/terraform/models/retrieve.md b/content/en/api/terraform/models/retrieve.md index e5f17d910..436f89648 100644 --- a/content/en/api/terraform/models/retrieve.md +++ b/content/en/api/terraform/models/retrieve.md @@ -1 +1 @@ -Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  \ No newline at end of file +Not Found - Claude API Docs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \ No newline at end of file diff --git a/content/en/api/typescript/beta.md b/content/en/api/typescript/beta.md index ee45d768f..460a1fc46 100644 --- a/content/en/api/typescript/beta.md +++ b/content/en/api/typescript/beta.md @@ -4,11 +4,11 @@ ### Anthropic Beta -- `AnthropicBeta = (string & {}) | "message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` +- `AnthropicBeta = (string & {}) | "message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -52,8 +52,6 @@ - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Beta API Error - `BetaAPIError` @@ -340,7 +338,7 @@ The Models API response can be used to determine which models are available for - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -384,8 +382,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaModelInfo` @@ -609,7 +605,7 @@ The Models API response can be used to determine information about a specific mo - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -653,8 +649,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaModelInfo` @@ -3936,11 +3930,15 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -6011,17 +6009,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id?: string | null` - - Body param: The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -6065,8 +6059,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - - `MessageCreateParamsNonStreaming extends MessageCreateParamsBase` - `stream?: false` @@ -7010,11 +7002,15 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -9922,11 +9918,15 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -11905,7 +11905,7 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -11949,8 +11949,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageTokensCount` @@ -11978,7 +11976,7 @@ const client = new Anthropic({ const betaMessageTokensCount = await client.beta.messages.countTokens({ messages: [{ content: 'string', role: 'user' }], - model: 'claude-opus-4-6', + model: 'claude-mythos-preview', }); console.log(betaMessageTokensCount.context_management); @@ -19169,11 +19167,15 @@ console.log(betaMessageTokensCount.context_management); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -24509,11 +24511,15 @@ console.log(betaMessageTokensCount.context_management); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -25749,11 +25755,15 @@ console.log(betaMessageTokensCount.context_management); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -36887,11 +36897,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -38960,17 +38974,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id?: string | null` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -39014,8 +39024,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` @@ -39155,7 +39163,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -39199,8 +39207,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` @@ -39339,7 +39345,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -39383,8 +39389,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` @@ -39516,7 +39520,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -39560,8 +39564,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` @@ -39692,7 +39694,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -39736,8 +39738,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaDeletedMessageBatch` @@ -39794,7 +39794,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -39838,8 +39838,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatchIndividualResponse` @@ -40781,11 +40779,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -42357,11 +42359,15 @@ console.log(betaMessageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -43725,11 +43731,15 @@ console.log(betaMessageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -45055,11 +45065,15 @@ console.log(betaMessageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -45360,23 +45374,381 @@ console.log(betaMessageBatchIndividualResponse.custom_id); - `"succeeded"` -# Files +# Agents -## Upload +## Create -`client.beta.files.upload(FileUploadParamsparams, RequestOptionsoptions?): FileMetadata` +`client.beta.agents.create(AgentCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsAgent` -**post** `/v1/files` +**post** `/v1/agents` -Upload File +Create Agent ### Parameters -- `params: FileUploadParams` +- `params: AgentCreateParams` - - `file: Uploadable` + - `model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` - Body param: The file to upload + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `BetaManagedAgentsModel = "claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more | (string & {})` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + Body param: Human-readable name for the agent. 1-256 characters. + + - `description?: string | null` + + Body param: Description of what the agent does. Up to 2048 characters. + + - `mcp_servers?: Array` + + Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + + - `skills?: Array` + + Body param: Skills available to the agent. Maximum 20. + + - `BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `system?: string | null` + + Body param: System prompt for the agent. Up to 100,000 characters. + + - `tools?: Array` + + Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled?: boolean | null` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` + + Default configuration for all tools in a toolset. + + - `enabled?: boolean | null` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled?: boolean | null` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` + + Default configuration for all tools from an MCP server. + + - `enabled?: boolean | null` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` - `betas?: Array` @@ -45384,7 +45756,7 @@ Upload File - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -45428,7 +45800,22613 @@ Upload File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsAgent = await client.beta.agents.create({ + model: 'claude-sonnet-4-6', + name: 'My First Agent', +}); + +console.log(betaManagedAgentsAgent.id); +``` + +## List + +`client.beta.agents.list(AgentListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `params: AgentListParams` + + - `createdAtGte?: string` + + Query param: Return agents created at or after this time (inclusive). + + - `createdAtLte?: string` + + Query param: Return agents created at or before this time (inclusive). + + - `include_archived?: boolean` + + Query param: Include archived agents in results. Defaults to false. + + - `limit?: number` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination cursor from a previous response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsAgent of client.beta.agents.list()) { + console.log(betaManagedAgentsAgent.id); +} +``` + +## Retrieve + +`client.beta.agents.retrieve(stringagentID, AgentRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsAgent` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `agentID: string` + +- `params: AgentRetrieveParams` + + - `version?: number` + + Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsAgent = await client.beta.agents.retrieve('agent_011CZkYpogX7uDKUyvBTophP'); + +console.log(betaManagedAgentsAgent.id); +``` + +## Update + +`client.beta.agents.update(stringagentID, AgentUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `agentID: string` + +- `params: AgentUpdateParams` + + - `version: number` + + Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + + - `description?: string | null` + + Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + + - `mcp_servers?: Array | null` + + Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + + - `model?: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `BetaManagedAgentsModel = "claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more | (string & {})` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name?: string` + + Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + + - `skills?: Array | null` + + Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `system?: string | null` + + Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + + - `tools?: Array | null` + + Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled?: boolean | null` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` + + Default configuration for all tools in a toolset. + + - `enabled?: boolean | null` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled?: boolean | null` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` + + Default configuration for all tools from an MCP server. + + - `enabled?: boolean | null` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsAgent = await client.beta.agents.update('agent_011CZkYpogX7uDKUyvBTophP', { + version: 1, +}); + +console.log(betaManagedAgentsAgent.id); +``` + +## Archive + +`client.beta.agents.archive(stringagentID, AgentArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `agentID: string` + +- `params: AgentArchiveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsAgent = await client.beta.agents.archive('agent_011CZkYpogX7uDKUyvBTophP'); + +console.log(betaManagedAgentsAgent.id); +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `BetaManagedAgentsAgentToolConfig` + + Configuration for a specific agent tool. + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Tool Config Params + +- `BetaManagedAgentsAgentToolConfigParams` + + Configuration override for a specific tool within a toolset. + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled?: boolean | null` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config + +- `BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled?: boolean | null` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset20260401 + +- `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled?: boolean | null` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` + + Default configuration for all tools in a toolset. + + - `enabled?: boolean | null` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Always Allow Policy + +- `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + +### Beta Managed Agents Always Ask Policy + +- `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Anthropic Skill + +- `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + +### Beta Managed Agents Anthropic Skill Params + +- `BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + +### Beta Managed Agents Custom Skill Params + +- `BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + +### Beta Managed Agents Custom Tool Input Schema + +- `BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + +### Beta Managed Agents Custom Tool Params + +- `BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + +### Beta Managed Agents MCP Server URL Definition + +- `BetaManagedAgentsMCPServerURLDefinition` + + URL-based MCP server connection as returned in API responses. + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + +### Beta Managed Agents MCP Tool Config + +- `BetaManagedAgentsMCPToolConfig` + + Resolved configuration for a specific MCP tool. + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Tool Config Params + +- `BetaManagedAgentsMCPToolConfigParams` + + Configuration override for a specific MCP tool. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled?: boolean | null` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset + +- `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + +### Beta Managed Agents MCP Toolset Default Config + +- `BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled?: boolean | null` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Params + +- `BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled?: boolean | null` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` + + Default configuration for all tools from an MCP server. + + - `enabled?: boolean | null` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Model + +- `BetaManagedAgentsModel = "claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more | (string & {})` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + +### Beta Managed Agents Model Config + +- `BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Model Config Params + +- `BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Skill Params + +- `BetaManagedAgentsSkillParams = BetaManagedAgentsAnthropicSkillParams | BetaManagedAgentsCustomSkillParams` + + Skill to load in the session container. + + - `BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `BetaManagedAgentsURLMCPServerParams` + + URL-based MCP server connection. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + +# Versions + +## List + +`client.beta.agents.versions.list(stringagentID, VersionListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agentID: string` + +- `params: VersionListParams` + + - `limit?: number` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination cursor. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsAgent of client.beta.agents.versions.list( + 'agent_011CZkYpogX7uDKUyvBTophP', +)) { + console.log(betaManagedAgentsAgent.id); +} +``` + +# Environments + +## Create + +`client.beta.environments.create(EnvironmentCreateParamsparams, RequestOptionsoptions?): BetaEnvironment` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `params: EnvironmentCreateParams` + + - `name: string` + + Body param: Human-readable name for the environment + + - `config?: BetaCloudConfigParams | null` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking?: BetaUnrestrictedNetwork | BetaLimitedNetworkParams | null` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers?: boolean | null` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers?: boolean | null` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts?: Array | null` + + Specifies domains the container can reach. + + - `packages?: BetaPackagesParams | null` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt?: Array | null` + + Ubuntu/Debian packages to install + + - `cargo?: Array | null` + + Rust packages to install + + - `gem?: Array | null` + + Ruby packages to install + + - `go?: Array | null` + + Go packages to install + + - `npm?: Array | null` + + Node.js packages to install + + - `pip?: Array | null` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `description?: string | null` + + Body param: Optional description of the environment + + - `metadata?: Record` + + Body param: User-provided metadata key-value pairs + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironment = await client.beta.environments.create({ name: 'python-data-analysis' }); + +console.log(betaEnvironment.id); +``` + +## List + +`client.beta.environments.list(EnvironmentListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `params: EnvironmentListParams` + + - `include_archived?: boolean` + + Query param: Include archived environments in the response + + - `limit?: number` + + Query param: Maximum number of environments to return + + - `page?: string | null` + + Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaEnvironment of client.beta.environments.list()) { + console.log(betaEnvironment.id); +} +``` + +## Retrieve + +`client.beta.environments.retrieve(stringenvironmentID, EnvironmentRetrieveParamsparams?, RequestOptionsoptions?): BetaEnvironment` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `environmentID: string` + +- `params: EnvironmentRetrieveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironment = await client.beta.environments.retrieve('env_011CZkZ9X2dpNyB7HsEFoRfW'); + +console.log(betaEnvironment.id); +``` + +## Update + +`client.beta.environments.update(stringenvironmentID, EnvironmentUpdateParamsparams, RequestOptionsoptions?): BetaEnvironment` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `environmentID: string` + +- `params: EnvironmentUpdateParams` + + - `config?: BetaCloudConfigParams | null` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking?: BetaUnrestrictedNetwork | BetaLimitedNetworkParams | null` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers?: boolean | null` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers?: boolean | null` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts?: Array | null` + + Specifies domains the container can reach. + + - `packages?: BetaPackagesParams | null` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt?: Array | null` + + Ubuntu/Debian packages to install + + - `cargo?: Array | null` + + Rust packages to install + + - `gem?: Array | null` + + Ruby packages to install + + - `go?: Array | null` + + Go packages to install + + - `npm?: Array | null` + + Node.js packages to install + + - `pip?: Array | null` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `description?: string | null` + + Body param: Updated description of the environment + + - `metadata?: Record` + + Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + + - `name?: string | null` + + Body param: Updated name for the environment + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironment = await client.beta.environments.update('env_011CZkZ9X2dpNyB7HsEFoRfW'); + +console.log(betaEnvironment.id); +``` + +## Delete + +`client.beta.environments.delete(stringenvironmentID, EnvironmentDeleteParamsparams?, RequestOptionsoptions?): BetaEnvironmentDeleteResponse` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `environmentID: string` + +- `params: EnvironmentDeleteParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironmentDeleteResponse` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + + - `"environment_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironmentDeleteResponse = await client.beta.environments.delete( + 'env_011CZkZ9X2dpNyB7HsEFoRfW', +); + +console.log(betaEnvironmentDeleteResponse.id); +``` + +## Archive + +`client.beta.environments.archive(stringenvironmentID, EnvironmentArchiveParamsparams?, RequestOptionsoptions?): BetaEnvironment` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `environmentID: string` + +- `params: EnvironmentArchiveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironment = await client.beta.environments.archive('env_011CZkZ9X2dpNyB7HsEFoRfW'); + +console.log(betaEnvironment.id); +``` + +## Domain Types + +### Beta Cloud Config + +- `BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + +### Beta Cloud Config Params + +- `BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking?: BetaUnrestrictedNetwork | BetaLimitedNetworkParams | null` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers?: boolean | null` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers?: boolean | null` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts?: Array | null` + + Specifies domains the container can reach. + + - `packages?: BetaPackagesParams | null` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt?: Array | null` + + Ubuntu/Debian packages to install + + - `cargo?: Array | null` + + Rust packages to install + + - `gem?: Array | null` + + Ruby packages to install + + - `go?: Array | null` + + Go packages to install + + - `npm?: Array | null` + + Node.js packages to install + + - `pip?: Array | null` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + +### Beta Environment + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `BetaEnvironmentDeleteResponse` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + + - `"environment_deleted"` + +### Beta Limited Network + +- `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + +### Beta Limited Network Params + +- `BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers?: boolean | null` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers?: boolean | null` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts?: Array | null` + + Specifies domains the container can reach. + +### Beta Packages + +- `BetaPackages` + + Packages (and their versions) available in this environment. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + +### Beta Packages Params + +- `BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt?: Array | null` + + Ubuntu/Debian packages to install + + - `cargo?: Array | null` + + Rust packages to install + + - `gem?: Array | null` + + Ruby packages to install + + - `go?: Array | null` + + Go packages to install + + - `npm?: Array | null` + + Node.js packages to install + + - `pip?: Array | null` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + +### Beta Unrestricted Network + +- `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + +# Sessions + +## Create + +`client.beta.sessions.create(SessionCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsSession` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `params: SessionCreateParams` + + - `agent: string | BetaManagedAgentsAgentParams` + + Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `string` + + - `BetaManagedAgentsAgentParams` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: string` + + The `agent` ID. + + - `type: "agent"` + + - `"agent"` + + - `version?: number` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + + - `environment_id: string` + + Body param: ID of the `environment` defining the container configuration for this session. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata attached to the session. + + - `resources?: Array` + + Body param: Resources (e.g. repositories, files) to mount into the session's container. + + - `BetaManagedAgentsGitHubRepositoryResourceParams` + + Mount a GitHub repository into the session's container. + + - `authorization_token: string` + + GitHub authorization token used to clone the repository. + + - `type: "github_repository"` + + - `"github_repository"` + + - `url: string` + + Github URL of the repository + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `mount_path?: string | null` + + Mount path in the container. Defaults to `/workspace/`. + + - `BetaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `mount_path?: string | null` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `title?: string | null` + + Body param: Human-readable session title. + + - `vault_ids?: Array` + + Body param: Vault IDs for stored credentials the agent can use during the session. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSession = await client.beta.sessions.create({ + agent: 'agent_011CZkYpogX7uDKUyvBTophP', + environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW', +}); + +console.log(betaManagedAgentsSession.id); +``` + +## List + +`client.beta.sessions.list(SessionListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `params: SessionListParams` + + - `agent_id?: string` + + Query param: Filter sessions created with this agent ID. + + - `agent_version?: number` + + Query param: Filter by agent version. Only applies when agent_id is also set. + + - `createdAtGt?: string` + + Query param: Return sessions created after this time (exclusive). + + - `createdAtGte?: string` + + Query param: Return sessions created at or after this time (inclusive). + + - `createdAtLt?: string` + + Query param: Return sessions created before this time (exclusive). + + - `createdAtLte?: string` + + Query param: Return sessions created at or before this time (inclusive). + + - `include_archived?: boolean` + + Query param: When true, includes archived sessions. Default: false (exclude archived). + + - `limit?: number` + + Query param: Maximum number of results to return. + + - `order?: "asc" | "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `"asc"` + + - `"desc"` + + - `page?: string` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsSession of client.beta.sessions.list()) { + console.log(betaManagedAgentsSession.id); +} +``` + +## Retrieve + +`client.beta.sessions.retrieve(stringsessionID, SessionRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsSession` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `sessionID: string` + +- `params: SessionRetrieveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSession = await client.beta.sessions.retrieve( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsSession.id); +``` + +## Update + +`client.beta.sessions.update(stringsessionID, SessionUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `sessionID: string` + +- `params: SessionUpdateParams` + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + + - `title?: string | null` + + Body param: Human-readable session title. + + - `vault_ids?: Array` + + Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSession = await client.beta.sessions.update('sesn_011CZkZAtmR3yMPDzynEDxu7'); + +console.log(betaManagedAgentsSession.id); +``` + +## Delete + +`client.beta.sessions.delete(stringsessionID, SessionDeleteParamsparams?, RequestOptionsoptions?): BetaManagedAgentsDeletedSession` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `sessionID: string` + +- `params: SessionDeleteParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedSession` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeletedSession = await client.beta.sessions.delete( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsDeletedSession.id); +``` + +## Archive + +`client.beta.sessions.archive(stringsessionID, SessionArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `sessionID: string` + +- `params: SessionArchiveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSession = await client.beta.sessions.archive( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsSession.id); +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `BetaManagedAgentsAgentParams` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: string` + + The `agent` ID. + + - `type: "agent"` + + - `"agent"` + + - `version?: number` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + +### Beta Managed Agents Cache Creation Usage + +- `BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Deleted Session + +- `BetaManagedAgentsDeletedSession` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Beta Managed Agents File Resource Params + +- `BetaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `mount_path?: string | null` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `BetaManagedAgentsGitHubRepositoryResourceParams` + + Mount a GitHub repository into the session's container. + + - `authorization_token: string` + + GitHub authorization token used to clone the repository. + + - `type: "github_repository"` + + - `"github_repository"` + + - `url: string` + + Github URL of the repository + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `mount_path?: string | null` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + +### Beta Managed Agents Session Stats + +- `BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + +# Events + +## List + +`client.beta.sessions.events.list(stringsessionID, EventListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `sessionID: string` + +- `params: EventListParams` + + - `limit?: number` + + Query param: Query parameter for limit + + - `order?: "asc" | "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"` + + - `"desc"` + + - `page?: string` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsSessionEvent of client.beta.sessions.events.list( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +)) { + console.log(betaManagedAgentsSessionEvent); +} +``` + +## Send + +`client.beta.sessions.events.send(stringsessionID, EventSendParamsparams, RequestOptionsoptions?): BetaManagedAgentsSendSessionEvents` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `sessionID: string` + +- `params: EventSendParams` + + - `events: Array` + + Body param: Events to send to the `session`. + + - `BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data?: Array` + + Sent events + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSendSessionEvents = await client.beta.sessions.events.send( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', + { + events: [ + { content: [{ text: 'Where is my order #1234?', type: 'text' }], type: 'user.message' }, + ], + }, +); + +console.log(betaManagedAgentsSendSessionEvents.data); +``` + +## Stream + +`client.beta.sessions.events.stream(stringsessionID, EventStreamParamsparams?, RequestOptionsoptions?): BetaManagedAgentsStreamSessionEvents | Stream` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `sessionID: string` + +- `params: EventStreamParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsStreamSessionEvents = await client.beta.sessions.events.stream( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsStreamSessionEvents); +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Agent Message Event + +- `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Base64 Document Source + +- `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Base64 Image Source + +- `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Billing Error + +- `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + +### Beta Managed Agents Document Block + +- `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + +### Beta Managed Agents Event Params + +- `BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams | BetaManagedAgentsUserInterruptEventParams | BetaManagedAgentsUserToolConfirmationEventParams | BetaManagedAgentsUserCustomToolResultEventParams` + + Union type for event parameters that can be sent to a session. + + - `BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents File Image Source + +- `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents Image Block + +- `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Retry Status Exhausted + +- `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + +### Beta Managed Agents Send Session Events + +- `BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data?: Array` + + Sent events + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + +### Beta Managed Agents Session Error Event + +- `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + +### Beta Managed Agents Session Event + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Stream Session Events + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Text Block + +- `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Unknown Error + +- `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + +### Beta Managed Agents URL Document Source + +- `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`client.beta.sessions.resources.add(stringsessionID, ResourceAddParamsparams, RequestOptionsoptions?): BetaManagedAgentsFileResource` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `sessionID: string` + +- `params: ResourceAddParams` + + - `file_id: string` + + Body param: ID of a previously uploaded file. + + - `type: "file"` + + Body param + + - `"file"` + + - `mount_path?: string | null` + + Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsFileResource = await client.beta.sessions.resources.add( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', + { file_id: 'file_011CNha8iCJcU1wXNR6q4V8w', type: 'file' }, +); + +console.log(betaManagedAgentsFileResource.id); +``` + +## List + +`client.beta.sessions.resources.list(stringsessionID, ResourceListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `sessionID: string` + +- `params: ResourceListParams` + + - `limit?: number` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `page?: string` + + Query param: Opaque cursor from a previous response's next_page field. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsSessionResource of client.beta.sessions.resources.list( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +)) { + console.log(betaManagedAgentsSessionResource); +} +``` + +## Retrieve + +`client.beta.sessions.resources.retrieve(stringresourceID, ResourceRetrieveParamsparams, RequestOptionsoptions?): ResourceRetrieveResponse` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `resourceID: string` + +- `params: ResourceRetrieveParams` + + - `session_id: string` + + Path param: Path parameter session_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const resource = await client.beta.sessions.resources.retrieve('sesrsc_011CZkZBJq5dWxk9fVLNcPht', { + session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7', +}); + +console.log(resource); +``` + +## Update + +`client.beta.sessions.resources.update(stringresourceID, ResourceUpdateParamsparams, RequestOptionsoptions?): ResourceUpdateResponse` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `resourceID: string` + +- `params: ResourceUpdateParams` + + - `session_id: string` + + Path param: Path parameter session_id + + - `authorization_token: string` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const resource = await client.beta.sessions.resources.update('sesrsc_011CZkZBJq5dWxk9fVLNcPht', { + session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7', + authorization_token: 'ghp_exampletoken', +}); + +console.log(resource); +``` + +## Delete + +`client.beta.sessions.resources.delete(stringresourceID, ResourceDeleteParamsparams, RequestOptionsoptions?): BetaManagedAgentsDeleteSessionResource` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `resourceID: string` + +- `params: ResourceDeleteParams` + + - `session_id: string` + + Path param: Path parameter session_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeleteSessionResource = await client.beta.sessions.resources.delete( + 'sesrsc_011CZkZBJq5dWxk9fVLNcPht', + { session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7' }, +); + +console.log(betaManagedAgentsDeleteSessionResource.id); +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Session Resource + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Resource Retrieve Response + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Resource Update Response + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +# Vaults + +## Create + +`client.beta.vaults.create(VaultCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsVault` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `params: VaultCreateParams` + + - `display_name: string` + + Body param: Human-readable name for the vault. 1-255 characters. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata to attach to the vault. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsVault = await client.beta.vaults.create({ display_name: 'Example vault' }); + +console.log(betaManagedAgentsVault.id); +``` + +## List + +`client.beta.vaults.list(VaultListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `params: VaultListParams` + + - `include_archived?: boolean` + + Query param: Whether to include archived vaults in the results. + + - `limit?: number` + + Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination token from a previous `list_vaults` response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsVault of client.beta.vaults.list()) { + console.log(betaManagedAgentsVault.id); +} +``` + +## Retrieve + +`client.beta.vaults.retrieve(stringvaultID, VaultRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsVault` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `vaultID: string` + +- `params: VaultRetrieveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsVault = await client.beta.vaults.retrieve('vlt_011CZkZDLs7fYzm1hXNPeRjv'); + +console.log(betaManagedAgentsVault.id); +``` + +## Update + +`client.beta.vaults.update(stringvaultID, VaultUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `vaultID: string` + +- `params: VaultUpdateParams` + + - `display_name?: string | null` + + Body param: Updated human-readable name for the vault. 1-255 characters. + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsVault = await client.beta.vaults.update('vlt_011CZkZDLs7fYzm1hXNPeRjv'); + +console.log(betaManagedAgentsVault.id); +``` + +## Delete + +`client.beta.vaults.delete(stringvaultID, VaultDeleteParamsparams?, RequestOptionsoptions?): BetaManagedAgentsDeletedVault` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `vaultID: string` + +- `params: VaultDeleteParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedVault` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeletedVault = await client.beta.vaults.delete( + 'vlt_011CZkZDLs7fYzm1hXNPeRjv', +); + +console.log(betaManagedAgentsDeletedVault.id); +``` + +## Archive + +`client.beta.vaults.archive(stringvaultID, VaultArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `vaultID: string` + +- `params: VaultArchiveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsVault = await client.beta.vaults.archive('vlt_011CZkZDLs7fYzm1hXNPeRjv'); + +console.log(betaManagedAgentsVault.id); +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `BetaManagedAgentsDeletedVault` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Beta Managed Agents Vault + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`client.beta.vaults.credentials.create(stringvaultID, CredentialCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vaultID: string` + +- `params: CredentialCreateParams` + + - `auth: BetaManagedAgentsMCPOAuthCreateParams | BetaManagedAgentsStaticBearerCreateParams` + + Body param: Authentication details for creating a credential. + + - `BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshParams | null` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `display_name?: string | null` + + Body param: Human-readable name for the credential. Up to 255 characters. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata to attach to the credential. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.create( + 'vlt_011CZkZDLs7fYzm1hXNPeRjv', + { + auth: { + token: 'bearer_exampletoken', + mcp_server_url: 'https://example-server.modelcontextprotocol.io/sse', + type: 'static_bearer', + }, + }, +); + +console.log(betaManagedAgentsCredential.id); +``` + +## List + +`client.beta.vaults.credentials.list(stringvaultID, CredentialListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vaultID: string` + +- `params: CredentialListParams` + + - `include_archived?: boolean` + + Query param: Whether to include archived credentials in the results. + + - `limit?: number` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination token from a previous `list_credentials` response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsCredential of client.beta.vaults.credentials.list( + 'vlt_011CZkZDLs7fYzm1hXNPeRjv', +)) { + console.log(betaManagedAgentsCredential.id); +} +``` + +## Retrieve + +`client.beta.vaults.credentials.retrieve(stringcredentialID, CredentialRetrieveParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialRetrieveParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.retrieve( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsCredential.id); +``` + +## Update + +`client.beta.vaults.credentials.update(stringcredentialID, CredentialUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialUpdateParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `auth?: BetaManagedAgentsMCPOAuthUpdateParams | BetaManagedAgentsStaticBearerUpdateParams` + + Body param: Updated authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token?: string | null` + + Updated OAuth access token. + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshUpdateParams | null` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token?: string | null` + + Updated OAuth refresh token. + + - `scope?: string | null` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token?: string | null` + + Updated static bearer token value. + + - `display_name?: string | null` + + Body param: Updated human-readable name for the credential. 1-255 characters. + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.update( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsCredential.id); +``` + +## Delete + +`client.beta.vaults.credentials.delete(stringcredentialID, CredentialDeleteParamsparams, RequestOptionsoptions?): BetaManagedAgentsDeletedCredential` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialDeleteParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeletedCredential = await client.beta.vaults.credentials.delete( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsDeletedCredential.id); +``` + +## Archive + +`client.beta.vaults.credentials.archive(stringcredentialID, CredentialArchiveParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialArchiveParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.archive( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsCredential.id); +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshParams | null` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token?: string | null` + + Updated OAuth refresh token. + + - `scope?: string | null` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token?: string | null` + + Updated OAuth access token. + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshUpdateParams | null` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token?: string | null` + + Updated OAuth refresh token. + + - `scope?: string | null` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token?: string | null` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + +# Files + +## Upload + +`client.beta.files.upload(FileUploadParamsparams, RequestOptionsoptions?): FileMetadata` + +**post** `/v1/files` + +Upload File + +### Parameters + +- `params: FileUploadParams` + + - `file: Uploadable` + + Body param: The file to upload + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` ### Returns @@ -45468,6 +68446,20 @@ Upload File Whether the file can be downloaded. + - `scope?: BetaFileScope | null` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```typescript @@ -45508,13 +68500,17 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. + - `scope_id?: string` + + Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -45558,8 +68554,6 @@ List Files - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `FileMetadata` @@ -45598,6 +68592,20 @@ List Files Whether the file can be downloaded. + - `scope?: BetaFileScope | null` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```typescript @@ -45635,7 +68643,7 @@ Download File - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -45679,8 +68687,6 @@ Download File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `unnamed_schema_1 = Response` @@ -45724,7 +68730,7 @@ Get File Metadata - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -45768,8 +68774,6 @@ Get File Metadata - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `FileMetadata` @@ -45808,6 +68812,20 @@ Get File Metadata Whether the file can be downloaded. + - `scope?: BetaFileScope | null` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```typescript @@ -45844,7 +68862,7 @@ Delete File - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -45888,8 +68906,6 @@ Delete File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `DeletedFile` @@ -45922,6 +68938,20 @@ console.log(deletedFile.id); ## Domain Types +### Beta File Scope + +- `BetaFileScope` + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Deleted File - `DeletedFile` @@ -45976,6 +69006,20 @@ console.log(deletedFile.id); Whether the file can be downloaded. + - `scope?: BetaFileScope | null` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + # Skills ## Create @@ -46008,7 +69052,7 @@ Create Skill - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -46052,8 +69096,6 @@ Create Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `SkillCreateResponse` @@ -46152,7 +69194,7 @@ List Skills - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -46196,8 +69238,6 @@ List Skills - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `SkillListResponse` @@ -46282,7 +69322,7 @@ Get Skill - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -46326,8 +69366,6 @@ Get Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `SkillRetrieveResponse` @@ -46411,7 +69449,7 @@ Delete Skill - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -46455,8 +69493,6 @@ Delete Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `SkillDeleteResponse` @@ -46672,7 +69708,7 @@ Create Skill Version - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -46716,8 +69752,6 @@ Create Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionCreateResponse` @@ -46814,7 +69848,7 @@ List Skill Versions - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -46858,8 +69892,6 @@ List Skill Versions - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionListResponse` @@ -46953,7 +69985,7 @@ Get Skill Version - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -46997,8 +70029,6 @@ Get Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionRetrieveResponse` @@ -47091,7 +70121,7 @@ Delete Skill Version - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -47135,8 +70165,6 @@ Delete Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionDeleteResponse` @@ -47328,586 +70356,3 @@ console.log(version.id); Deleted object type. For Skill Versions, this is always `"skill_version_deleted"`. - -# User Profiles - -## Create - -`client.beta.userProfiles.create(UserProfileCreateParamsparams, RequestOptionsoptions?): BetaUserProfile` - -**post** `/v1/user_profiles` - -Create User Profile - -### Parameters - -- `params: UserProfileCreateParams` - - - `external_id?: string | null` - - Body param - - - `metadata?: Record` - - Body param: Free-form key-value data to attach to this user profile. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. Values must be non-empty strings. - - - `betas?: Array` - - Header param: Optional header to specify the beta version(s) you want to use. - - - `(string & {})` - - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `BetaUserProfile` - - - `id: string` - - - `created_at: string` - - A timestamp in RFC 3339 format - - - `metadata: Record` - - - `trust_grants: Record` - - - `status: string` - - - `type: string` - - - `updated_at: string` - - A timestamp in RFC 3339 format - - - `external_id?: string | null` - -### Example - -```typescript -import Anthropic from '@anthropic-ai/sdk'; - -const client = new Anthropic({ - apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted -}); - -const betaUserProfile = await client.beta.userProfiles.create(); - -console.log(betaUserProfile.id); -``` - -## List - -`client.beta.userProfiles.list(UserProfileListParamsparams?, RequestOptionsoptions?): PageCursorV2` - -**get** `/v1/user_profiles` - -List User Profiles - -### Parameters - -- `params: UserProfileListParams` - - - `limit?: number` - - Query param: Query parameter for limit - - - `order?: "asc" | "desc"` - - Query param: Query parameter for order - - - `"asc"` - - - `"desc"` - - - `page?: string` - - Query param: Query parameter for page - - - `betas?: Array` - - Header param: Optional header to specify the beta version(s) you want to use. - - - `(string & {})` - - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `BetaUserProfile` - - - `id: string` - - - `created_at: string` - - A timestamp in RFC 3339 format - - - `metadata: Record` - - - `trust_grants: Record` - - - `status: string` - - - `type: string` - - - `updated_at: string` - - A timestamp in RFC 3339 format - - - `external_id?: string | null` - -### Example - -```typescript -import Anthropic from '@anthropic-ai/sdk'; - -const client = new Anthropic({ - apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted -}); - -// Automatically fetches more pages as needed. -for await (const betaUserProfile of client.beta.userProfiles.list()) { - console.log(betaUserProfile.id); -} -``` - -## Retrieve - -`client.beta.userProfiles.retrieve(stringid, UserProfileRetrieveParamsparams?, RequestOptionsoptions?): BetaUserProfile` - -**get** `/v1/user_profiles/{id}` - -Get User Profile - -### Parameters - -- `id: string` - -- `params: UserProfileRetrieveParams` - - - `betas?: Array` - - Optional header to specify the beta version(s) you want to use. - - - `(string & {})` - - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `BetaUserProfile` - - - `id: string` - - - `created_at: string` - - A timestamp in RFC 3339 format - - - `metadata: Record` - - - `trust_grants: Record` - - - `status: string` - - - `type: string` - - - `updated_at: string` - - A timestamp in RFC 3339 format - - - `external_id?: string | null` - -### Example - -```typescript -import Anthropic from '@anthropic-ai/sdk'; - -const client = new Anthropic({ - apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted -}); - -const betaUserProfile = await client.beta.userProfiles.retrieve('id'); - -console.log(betaUserProfile.id); -``` - -## Update - -`client.beta.userProfiles.update(stringid, UserProfileUpdateParamsparams, RequestOptionsoptions?): BetaUserProfile` - -**post** `/v1/user_profiles/{id}` - -Update User Profile - -### Parameters - -- `id: string` - -- `params: UserProfileUpdateParams` - - - `external_id?: string | null` - - Body param - - - `metadata?: Record` - - Body param: Key-value pairs to merge into the stored metadata. Keys provided overwrite existing values. To remove a key, set its value to an empty string. Keys not provided are left unchanged. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. - - - `betas?: Array` - - Header param: Optional header to specify the beta version(s) you want to use. - - - `(string & {})` - - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `BetaUserProfile` - - - `id: string` - - - `created_at: string` - - A timestamp in RFC 3339 format - - - `metadata: Record` - - - `trust_grants: Record` - - - `status: string` - - - `type: string` - - - `updated_at: string` - - A timestamp in RFC 3339 format - - - `external_id?: string | null` - -### Example - -```typescript -import Anthropic from '@anthropic-ai/sdk'; - -const client = new Anthropic({ - apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted -}); - -const betaUserProfile = await client.beta.userProfiles.update('id'); - -console.log(betaUserProfile.id); -``` - -## Create Enrollment URL - -`client.beta.userProfiles.createEnrollmentURL(stringid, UserProfileCreateEnrollmentURLParamsparams?, RequestOptionsoptions?): BetaUserProfileEnrollmentURL` - -**post** `/v1/user_profiles/{id}/enrollment_url` - -Create Enrollment URL - -### Parameters - -- `id: string` - -- `params: UserProfileCreateEnrollmentURLParams` - - - `betas?: Array` - - Optional header to specify the beta version(s) you want to use. - - - `(string & {})` - - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `BetaUserProfileEnrollmentURL` - - - `expires_at: string` - - A timestamp in RFC 3339 format - - - `type: string` - - - `url: string` - -### Example - -```typescript -import Anthropic from '@anthropic-ai/sdk'; - -const client = new Anthropic({ - apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted -}); - -const betaUserProfileEnrollmentURL = await client.beta.userProfiles.createEnrollmentURL('id'); - -console.log(betaUserProfileEnrollmentURL.expires_at); -``` - -## Domain Types - -### Beta User Profile - -- `BetaUserProfile` - - - `id: string` - - - `created_at: string` - - A timestamp in RFC 3339 format - - - `metadata: Record` - - - `trust_grants: Record` - - - `status: string` - - - `type: string` - - - `updated_at: string` - - A timestamp in RFC 3339 format - - - `external_id?: string | null` - -### Beta User Profile Enrollment URL - -- `BetaUserProfileEnrollmentURL` - - - `expires_at: string` - - A timestamp in RFC 3339 format - - - `type: string` - - - `url: string` - -### Beta User Profile Trust Grant - -- `BetaUserProfileTrustGrant` - - - `status: string` diff --git a/content/en/api/typescript/beta/agents.md b/content/en/api/typescript/beta/agents.md new file mode 100644 index 000000000..a66f2ba7e --- /dev/null +++ b/content/en/api/typescript/beta/agents.md @@ -0,0 +1,4272 @@ +# Agents + +## Create + +`client.beta.agents.create(AgentCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsAgent` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `params: AgentCreateParams` + + - `model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `BetaManagedAgentsModel = "claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more | (string & {})` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + Body param: Human-readable name for the agent. 1-256 characters. + + - `description?: string | null` + + Body param: Description of what the agent does. Up to 2048 characters. + + - `mcp_servers?: Array` + + Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + + - `skills?: Array` + + Body param: Skills available to the agent. Maximum 20. + + - `BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `system?: string | null` + + Body param: System prompt for the agent. Up to 100,000 characters. + + - `tools?: Array` + + Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled?: boolean | null` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` + + Default configuration for all tools in a toolset. + + - `enabled?: boolean | null` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled?: boolean | null` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` + + Default configuration for all tools from an MCP server. + + - `enabled?: boolean | null` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsAgent = await client.beta.agents.create({ + model: 'claude-sonnet-4-6', + name: 'My First Agent', +}); + +console.log(betaManagedAgentsAgent.id); +``` + +## List + +`client.beta.agents.list(AgentListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `params: AgentListParams` + + - `createdAtGte?: string` + + Query param: Return agents created at or after this time (inclusive). + + - `createdAtLte?: string` + + Query param: Return agents created at or before this time (inclusive). + + - `include_archived?: boolean` + + Query param: Include archived agents in results. Defaults to false. + + - `limit?: number` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination cursor from a previous response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsAgent of client.beta.agents.list()) { + console.log(betaManagedAgentsAgent.id); +} +``` + +## Retrieve + +`client.beta.agents.retrieve(stringagentID, AgentRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsAgent` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `agentID: string` + +- `params: AgentRetrieveParams` + + - `version?: number` + + Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsAgent = await client.beta.agents.retrieve('agent_011CZkYpogX7uDKUyvBTophP'); + +console.log(betaManagedAgentsAgent.id); +``` + +## Update + +`client.beta.agents.update(stringagentID, AgentUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `agentID: string` + +- `params: AgentUpdateParams` + + - `version: number` + + Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + + - `description?: string | null` + + Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + + - `mcp_servers?: Array | null` + + Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + + - `model?: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `BetaManagedAgentsModel = "claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more | (string & {})` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name?: string` + + Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + + - `skills?: Array | null` + + Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `system?: string | null` + + Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + + - `tools?: Array | null` + + Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled?: boolean | null` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` + + Default configuration for all tools in a toolset. + + - `enabled?: boolean | null` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled?: boolean | null` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` + + Default configuration for all tools from an MCP server. + + - `enabled?: boolean | null` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsAgent = await client.beta.agents.update('agent_011CZkYpogX7uDKUyvBTophP', { + version: 1, +}); + +console.log(betaManagedAgentsAgent.id); +``` + +## Archive + +`client.beta.agents.archive(stringagentID, AgentArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `agentID: string` + +- `params: AgentArchiveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsAgent = await client.beta.agents.archive('agent_011CZkYpogX7uDKUyvBTophP'); + +console.log(betaManagedAgentsAgent.id); +``` + +## Domain Types + +### Beta Managed Agents Agent + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Beta Managed Agents Agent Tool Config + +- `BetaManagedAgentsAgentToolConfig` + + Configuration for a specific agent tool. + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Tool Config Params + +- `BetaManagedAgentsAgentToolConfigParams` + + Configuration override for a specific tool within a toolset. + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled?: boolean | null` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config + +- `BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset Default Config Params + +- `BetaManagedAgentsAgentToolsetDefaultConfigParams` + + Default configuration for all tools in a toolset. + + - `enabled?: boolean | null` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Agent Toolset20260401 + +- `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + +### Beta Managed Agents Agent Toolset20260401 Params + +- `BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled?: boolean | null` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` + + Default configuration for all tools in a toolset. + + - `enabled?: boolean | null` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Always Allow Policy + +- `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + +### Beta Managed Agents Always Ask Policy + +- `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Anthropic Skill + +- `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + +### Beta Managed Agents Anthropic Skill Params + +- `BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Skill + +- `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + +### Beta Managed Agents Custom Skill Params + +- `BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents Custom Tool + +- `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + +### Beta Managed Agents Custom Tool Input Schema + +- `BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + +### Beta Managed Agents Custom Tool Params + +- `BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + +### Beta Managed Agents MCP Server URL Definition + +- `BetaManagedAgentsMCPServerURLDefinition` + + URL-based MCP server connection as returned in API responses. + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + +### Beta Managed Agents MCP Tool Config + +- `BetaManagedAgentsMCPToolConfig` + + Resolved configuration for a specific MCP tool. + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Tool Config Params + +- `BetaManagedAgentsMCPToolConfigParams` + + Configuration override for a specific MCP tool. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled?: boolean | null` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset + +- `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + +### Beta Managed Agents MCP Toolset Default Config + +- `BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Default Config Params + +- `BetaManagedAgentsMCPToolsetDefaultConfigParams` + + Default configuration for all tools from an MCP server. + + - `enabled?: boolean | null` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents MCP Toolset Params + +- `BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled?: boolean | null` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` + + Default configuration for all tools from an MCP server. + + - `enabled?: boolean | null` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + +### Beta Managed Agents Model + +- `BetaManagedAgentsModel = "claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more | (string & {})` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + +### Beta Managed Agents Model Config + +- `BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Model Config Params + +- `BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Skill Params + +- `BetaManagedAgentsSkillParams = BetaManagedAgentsAnthropicSkillParams | BetaManagedAgentsCustomSkillParams` + + Skill to load in the session container. + + - `BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + +### Beta Managed Agents URL MCP Server Params + +- `BetaManagedAgentsURLMCPServerParams` + + URL-based MCP server connection. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + +# Versions + +## List + +`client.beta.agents.versions.list(stringagentID, VersionListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agentID: string` + +- `params: VersionListParams` + + - `limit?: number` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination cursor. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsAgent of client.beta.agents.versions.list( + 'agent_011CZkYpogX7uDKUyvBTophP', +)) { + console.log(betaManagedAgentsAgent.id); +} +``` diff --git a/content/en/api/typescript/beta/agents/archive.md b/content/en/api/typescript/beta/agents/archive.md new file mode 100644 index 000000000..1d808da53 --- /dev/null +++ b/content/en/api/typescript/beta/agents/archive.md @@ -0,0 +1,371 @@ +## Archive + +`client.beta.agents.archive(stringagentID, AgentArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}/archive` + +Archive Agent + +### Parameters + +- `agentID: string` + +- `params: AgentArchiveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsAgent = await client.beta.agents.archive('agent_011CZkYpogX7uDKUyvBTophP'); + +console.log(betaManagedAgentsAgent.id); +``` diff --git a/content/en/api/typescript/beta/agents/create.md b/content/en/api/typescript/beta/agents/create.md new file mode 100644 index 000000000..21761ac23 --- /dev/null +++ b/content/en/api/typescript/beta/agents/create.md @@ -0,0 +1,734 @@ +## Create + +`client.beta.agents.create(AgentCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsAgent` + +**post** `/v1/agents` + +Create Agent + +### Parameters + +- `params: AgentCreateParams` + + - `model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control + + - `BetaManagedAgentsModel = "claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more | (string & {})` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + Body param: Human-readable name for the agent. 1-256 characters. + + - `description?: string | null` + + Body param: Description of what the agent does. Up to 2048 characters. + + - `mcp_servers?: Array` + + Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. + + - `skills?: Array` + + Body param: Skills available to the agent. Maximum 20. + + - `BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `system?: string | null` + + Body param: System prompt for the agent. Up to 100,000 characters. + + - `tools?: Array` + + Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. + + - `BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled?: boolean | null` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` + + Default configuration for all tools in a toolset. + + - `enabled?: boolean | null` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled?: boolean | null` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` + + Default configuration for all tools from an MCP server. + + - `enabled?: boolean | null` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsAgent = await client.beta.agents.create({ + model: 'claude-sonnet-4-6', + name: 'My First Agent', +}); + +console.log(betaManagedAgentsAgent.id); +``` diff --git a/content/en/api/typescript/beta/agents/list.md b/content/en/api/typescript/beta/agents/list.md new file mode 100644 index 000000000..3557fa886 --- /dev/null +++ b/content/en/api/typescript/beta/agents/list.md @@ -0,0 +1,390 @@ +## List + +`client.beta.agents.list(AgentListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/agents` + +List Agents + +### Parameters + +- `params: AgentListParams` + + - `createdAtGte?: string` + + Query param: Return agents created at or after this time (inclusive). + + - `createdAtLte?: string` + + Query param: Return agents created at or before this time (inclusive). + + - `include_archived?: boolean` + + Query param: Include archived agents in results. Defaults to false. + + - `limit?: number` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination cursor from a previous response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsAgent of client.beta.agents.list()) { + console.log(betaManagedAgentsAgent.id); +} +``` diff --git a/content/en/api/typescript/beta/agents/retrieve.md b/content/en/api/typescript/beta/agents/retrieve.md new file mode 100644 index 000000000..b498d6611 --- /dev/null +++ b/content/en/api/typescript/beta/agents/retrieve.md @@ -0,0 +1,375 @@ +## Retrieve + +`client.beta.agents.retrieve(stringagentID, AgentRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsAgent` + +**get** `/v1/agents/{agent_id}` + +Get Agent + +### Parameters + +- `agentID: string` + +- `params: AgentRetrieveParams` + + - `version?: number` + + Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsAgent = await client.beta.agents.retrieve('agent_011CZkYpogX7uDKUyvBTophP'); + +console.log(betaManagedAgentsAgent.id); +``` diff --git a/content/en/api/typescript/beta/agents/update.md b/content/en/api/typescript/beta/agents/update.md new file mode 100644 index 000000000..0843a3bdc --- /dev/null +++ b/content/en/api/typescript/beta/agents/update.md @@ -0,0 +1,739 @@ +## Update + +`client.beta.agents.update(stringagentID, AgentUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsAgent` + +**post** `/v1/agents/{agent_id}` + +Update Agent + +### Parameters + +- `agentID: string` + +- `params: AgentUpdateParams` + + - `version: number` + + Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. + + - `description?: string | null` + + Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. + + - `mcp_servers?: Array | null` + + Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. + + - `name: string` + + Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + + - `type: "url"` + + - `"url"` + + - `url: string` + + Endpoint URL for the MCP server. + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. + + - `model?: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` + + Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. + + - `BetaManagedAgentsModel = "claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more | (string & {})` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `BetaManagedAgentsModelConfigParams` + + An object that defines additional configuration control over model use + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name?: string` + + Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. + + - `skills?: Array | null` + + Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. + + - `BetaManagedAgentsAnthropicSkillParams` + + An Anthropic-managed skill. + + - `skill_id: string` + + Identifier of the Anthropic skill (e.g., "xlsx"). + + - `type: "anthropic"` + + - `"anthropic"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `BetaManagedAgentsCustomSkillParams` + + A user-created custom skill. + + - `skill_id: string` + + Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + + - `type: "custom"` + + - `"custom"` + + - `version?: string | null` + + Version to pin. Defaults to latest if omitted. + + - `system?: string | null` + + Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. + + - `tools?: Array | null` + + Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. + + - `BetaManagedAgentsAgentToolset20260401Params` + + Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `enabled?: boolean | null` + + Whether this tool is enabled and available to Claude. Overrides the default_config setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` + + Default configuration for all tools in a toolset. + + - `enabled?: boolean | null` + + Whether tools are enabled and available to Claude by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsMCPToolsetParams` + + Configuration for tools from an MCP server defined in `mcp_servers`. + + - `mcp_server_name: string` + + Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `configs?: Array` + + Per-tool configuration overrides. + + - `name: string` + + Name of the MCP tool to configure. 1-128 characters. + + - `enabled?: boolean | null` + + Whether this tool is enabled. Overrides the `default_config` setting. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` + + Default configuration for all tools from an MCP server. + + - `enabled?: boolean | null` + + Whether tools are enabled by default. Defaults to true if not specified. + + - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `BetaManagedAgentsCustomToolParams` + + A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. + + - `description: string` + + Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + + - `type: "custom"` + + - `"custom"` + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsAgent = await client.beta.agents.update('agent_011CZkYpogX7uDKUyvBTophP', { + version: 1, +}); + +console.log(betaManagedAgentsAgent.id); +``` diff --git a/content/en/api/typescript/beta/agents/versions.md b/content/en/api/typescript/beta/agents/versions.md new file mode 100644 index 000000000..120af2762 --- /dev/null +++ b/content/en/api/typescript/beta/agents/versions.md @@ -0,0 +1,384 @@ +# Versions + +## List + +`client.beta.agents.versions.list(stringagentID, VersionListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agentID: string` + +- `params: VersionListParams` + + - `limit?: number` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination cursor. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsAgent of client.beta.agents.versions.list( + 'agent_011CZkYpogX7uDKUyvBTophP', +)) { + console.log(betaManagedAgentsAgent.id); +} +``` diff --git a/content/en/api/typescript/beta/agents/versions/list.md b/content/en/api/typescript/beta/agents/versions/list.md new file mode 100644 index 000000000..0a9694ede --- /dev/null +++ b/content/en/api/typescript/beta/agents/versions/list.md @@ -0,0 +1,382 @@ +## List + +`client.beta.agents.versions.list(stringagentID, VersionListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/agents/{agent_id}/versions` + +List Agent Versions + +### Parameters + +- `agentID: string` + +- `params: VersionListParams` + + - `limit?: number` + + Query param: Maximum results per page. Default 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination cursor. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsAgent` + + A Managed Agents `agent`. + + - `id: string` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `metadata: Record` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `version: number` + + The agent's current version. Starts at 1 and increments when the agent is modified. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsAgent of client.beta.agents.versions.list( + 'agent_011CZkYpogX7uDKUyvBTophP', +)) { + console.log(betaManagedAgentsAgent.id); +} +``` diff --git a/content/en/api/typescript/beta/environments.md b/content/en/api/typescript/beta/environments.md new file mode 100644 index 000000000..fcc7f803f --- /dev/null +++ b/content/en/api/typescript/beta/environments.md @@ -0,0 +1,1743 @@ +# Environments + +## Create + +`client.beta.environments.create(EnvironmentCreateParamsparams, RequestOptionsoptions?): BetaEnvironment` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `params: EnvironmentCreateParams` + + - `name: string` + + Body param: Human-readable name for the environment + + - `config?: BetaCloudConfigParams | null` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking?: BetaUnrestrictedNetwork | BetaLimitedNetworkParams | null` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers?: boolean | null` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers?: boolean | null` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts?: Array | null` + + Specifies domains the container can reach. + + - `packages?: BetaPackagesParams | null` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt?: Array | null` + + Ubuntu/Debian packages to install + + - `cargo?: Array | null` + + Rust packages to install + + - `gem?: Array | null` + + Ruby packages to install + + - `go?: Array | null` + + Go packages to install + + - `npm?: Array | null` + + Node.js packages to install + + - `pip?: Array | null` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `description?: string | null` + + Body param: Optional description of the environment + + - `metadata?: Record` + + Body param: User-provided metadata key-value pairs + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironment = await client.beta.environments.create({ name: 'python-data-analysis' }); + +console.log(betaEnvironment.id); +``` + +## List + +`client.beta.environments.list(EnvironmentListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `params: EnvironmentListParams` + + - `include_archived?: boolean` + + Query param: Include archived environments in the response + + - `limit?: number` + + Query param: Maximum number of environments to return + + - `page?: string | null` + + Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaEnvironment of client.beta.environments.list()) { + console.log(betaEnvironment.id); +} +``` + +## Retrieve + +`client.beta.environments.retrieve(stringenvironmentID, EnvironmentRetrieveParamsparams?, RequestOptionsoptions?): BetaEnvironment` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `environmentID: string` + +- `params: EnvironmentRetrieveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironment = await client.beta.environments.retrieve('env_011CZkZ9X2dpNyB7HsEFoRfW'); + +console.log(betaEnvironment.id); +``` + +## Update + +`client.beta.environments.update(stringenvironmentID, EnvironmentUpdateParamsparams, RequestOptionsoptions?): BetaEnvironment` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `environmentID: string` + +- `params: EnvironmentUpdateParams` + + - `config?: BetaCloudConfigParams | null` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking?: BetaUnrestrictedNetwork | BetaLimitedNetworkParams | null` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers?: boolean | null` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers?: boolean | null` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts?: Array | null` + + Specifies domains the container can reach. + + - `packages?: BetaPackagesParams | null` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt?: Array | null` + + Ubuntu/Debian packages to install + + - `cargo?: Array | null` + + Rust packages to install + + - `gem?: Array | null` + + Ruby packages to install + + - `go?: Array | null` + + Go packages to install + + - `npm?: Array | null` + + Node.js packages to install + + - `pip?: Array | null` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `description?: string | null` + + Body param: Updated description of the environment + + - `metadata?: Record` + + Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + + - `name?: string | null` + + Body param: Updated name for the environment + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironment = await client.beta.environments.update('env_011CZkZ9X2dpNyB7HsEFoRfW'); + +console.log(betaEnvironment.id); +``` + +## Delete + +`client.beta.environments.delete(stringenvironmentID, EnvironmentDeleteParamsparams?, RequestOptionsoptions?): BetaEnvironmentDeleteResponse` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `environmentID: string` + +- `params: EnvironmentDeleteParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironmentDeleteResponse` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + + - `"environment_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironmentDeleteResponse = await client.beta.environments.delete( + 'env_011CZkZ9X2dpNyB7HsEFoRfW', +); + +console.log(betaEnvironmentDeleteResponse.id); +``` + +## Archive + +`client.beta.environments.archive(stringenvironmentID, EnvironmentArchiveParamsparams?, RequestOptionsoptions?): BetaEnvironment` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `environmentID: string` + +- `params: EnvironmentArchiveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironment = await client.beta.environments.archive('env_011CZkZ9X2dpNyB7HsEFoRfW'); + +console.log(betaEnvironment.id); +``` + +## Domain Types + +### Beta Cloud Config + +- `BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + +### Beta Cloud Config Params + +- `BetaCloudConfigParams` + + Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking?: BetaUnrestrictedNetwork | BetaLimitedNetworkParams | null` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers?: boolean | null` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers?: boolean | null` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts?: Array | null` + + Specifies domains the container can reach. + + - `packages?: BetaPackagesParams | null` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt?: Array | null` + + Ubuntu/Debian packages to install + + - `cargo?: Array | null` + + Rust packages to install + + - `gem?: Array | null` + + Ruby packages to install + + - `go?: Array | null` + + Go packages to install + + - `npm?: Array | null` + + Node.js packages to install + + - `pip?: Array | null` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + +### Beta Environment + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Beta Environment Delete Response + +- `BetaEnvironmentDeleteResponse` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + + - `"environment_deleted"` + +### Beta Limited Network + +- `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + +### Beta Limited Network Params + +- `BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers?: boolean | null` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers?: boolean | null` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts?: Array | null` + + Specifies domains the container can reach. + +### Beta Packages + +- `BetaPackages` + + Packages (and their versions) available in this environment. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + +### Beta Packages Params + +- `BetaPackagesParams` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt?: Array | null` + + Ubuntu/Debian packages to install + + - `cargo?: Array | null` + + Rust packages to install + + - `gem?: Array | null` + + Ruby packages to install + + - `go?: Array | null` + + Go packages to install + + - `npm?: Array | null` + + Node.js packages to install + + - `pip?: Array | null` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + +### Beta Unrestricted Network + +- `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` diff --git a/content/en/api/typescript/beta/environments/archive.md b/content/en/api/typescript/beta/environments/archive.md new file mode 100644 index 000000000..8e6fe64f2 --- /dev/null +++ b/content/en/api/typescript/beta/environments/archive.md @@ -0,0 +1,197 @@ +## Archive + +`client.beta.environments.archive(stringenvironmentID, EnvironmentArchiveParamsparams?, RequestOptionsoptions?): BetaEnvironment` + +**post** `/v1/environments/{environment_id}/archive` + +Archive an environment by ID. Archived environments cannot be used to create new sessions. + +### Parameters + +- `environmentID: string` + +- `params: EnvironmentArchiveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironment = await client.beta.environments.archive('env_011CZkZ9X2dpNyB7HsEFoRfW'); + +console.log(betaEnvironment.id); +``` diff --git a/content/en/api/typescript/beta/environments/create.md b/content/en/api/typescript/beta/environments/create.md new file mode 100644 index 000000000..ae62c69ff --- /dev/null +++ b/content/en/api/typescript/beta/environments/create.md @@ -0,0 +1,295 @@ +## Create + +`client.beta.environments.create(EnvironmentCreateParamsparams, RequestOptionsoptions?): BetaEnvironment` + +**post** `/v1/environments` + +Create a new environment with the specified configuration. + +### Parameters + +- `params: EnvironmentCreateParams` + + - `name: string` + + Body param: Human-readable name for the environment + + - `config?: BetaCloudConfigParams | null` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking?: BetaUnrestrictedNetwork | BetaLimitedNetworkParams | null` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers?: boolean | null` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers?: boolean | null` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts?: Array | null` + + Specifies domains the container can reach. + + - `packages?: BetaPackagesParams | null` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt?: Array | null` + + Ubuntu/Debian packages to install + + - `cargo?: Array | null` + + Rust packages to install + + - `gem?: Array | null` + + Ruby packages to install + + - `go?: Array | null` + + Go packages to install + + - `npm?: Array | null` + + Node.js packages to install + + - `pip?: Array | null` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `description?: string | null` + + Body param: Optional description of the environment + + - `metadata?: Record` + + Body param: User-provided metadata key-value pairs + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironment = await client.beta.environments.create({ name: 'python-data-analysis' }); + +console.log(betaEnvironment.id); +``` diff --git a/content/en/api/typescript/beta/environments/delete.md b/content/en/api/typescript/beta/environments/delete.md new file mode 100644 index 000000000..63c7ac870 --- /dev/null +++ b/content/en/api/typescript/beta/environments/delete.md @@ -0,0 +1,95 @@ +## Delete + +`client.beta.environments.delete(stringenvironmentID, EnvironmentDeleteParamsparams?, RequestOptionsoptions?): BetaEnvironmentDeleteResponse` + +**delete** `/v1/environments/{environment_id}` + +Delete an environment by ID. Returns a confirmation of the deletion. + +### Parameters + +- `environmentID: string` + +- `params: EnvironmentDeleteParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironmentDeleteResponse` + + Response after deleting an environment. + + - `id: string` + + Environment identifier + + - `type: "environment_deleted"` + + The type of response + + - `"environment_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironmentDeleteResponse = await client.beta.environments.delete( + 'env_011CZkZ9X2dpNyB7HsEFoRfW', +); + +console.log(betaEnvironmentDeleteResponse.id); +``` diff --git a/content/en/api/typescript/beta/environments/list.md b/content/en/api/typescript/beta/environments/list.md new file mode 100644 index 000000000..86f6cad09 --- /dev/null +++ b/content/en/api/typescript/beta/environments/list.md @@ -0,0 +1,208 @@ +## List + +`client.beta.environments.list(EnvironmentListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/environments` + +List environments with pagination support. + +### Parameters + +- `params: EnvironmentListParams` + + - `include_archived?: boolean` + + Query param: Include archived environments in the response + + - `limit?: number` + + Query param: Maximum number of environments to return + + - `page?: string | null` + + Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaEnvironment of client.beta.environments.list()) { + console.log(betaEnvironment.id); +} +``` diff --git a/content/en/api/typescript/beta/environments/retrieve.md b/content/en/api/typescript/beta/environments/retrieve.md new file mode 100644 index 000000000..f9e550e6c --- /dev/null +++ b/content/en/api/typescript/beta/environments/retrieve.md @@ -0,0 +1,197 @@ +## Retrieve + +`client.beta.environments.retrieve(stringenvironmentID, EnvironmentRetrieveParamsparams?, RequestOptionsoptions?): BetaEnvironment` + +**get** `/v1/environments/{environment_id}` + +Retrieve a specific environment by ID. + +### Parameters + +- `environmentID: string` + +- `params: EnvironmentRetrieveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironment = await client.beta.environments.retrieve('env_011CZkZ9X2dpNyB7HsEFoRfW'); + +console.log(betaEnvironment.id); +``` diff --git a/content/en/api/typescript/beta/environments/update.md b/content/en/api/typescript/beta/environments/update.md new file mode 100644 index 000000000..54db476d2 --- /dev/null +++ b/content/en/api/typescript/beta/environments/update.md @@ -0,0 +1,297 @@ +## Update + +`client.beta.environments.update(stringenvironmentID, EnvironmentUpdateParamsparams, RequestOptionsoptions?): BetaEnvironment` + +**post** `/v1/environments/{environment_id}` + +Update an existing environment's configuration. + +### Parameters + +- `environmentID: string` + +- `params: EnvironmentUpdateParams` + + - `config?: BetaCloudConfigParams | null` + + Body param: Request params for `cloud` environment configuration. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `networking?: BetaUnrestrictedNetwork | BetaLimitedNetworkParams | null` + + Network configuration policy. Omit on update to preserve the existing value. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetworkParams` + + Limited network request params. + + Fields default to null; on update, omitted fields preserve the + existing value. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `allow_mcp_servers?: boolean | null` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allow_package_managers?: boolean | null` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. + + - `allowed_hosts?: Array | null` + + Specifies domains the container can reach. + + - `packages?: BetaPackagesParams | null` + + Specify packages (and optionally their versions) available in this environment. + + When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. + + - `apt?: Array | null` + + Ubuntu/Debian packages to install + + - `cargo?: Array | null` + + Rust packages to install + + - `gem?: Array | null` + + Ruby packages to install + + - `go?: Array | null` + + Go packages to install + + - `npm?: Array | null` + + Node.js packages to install + + - `pip?: Array | null` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `description?: string | null` + + Body param: Updated description of the environment + + - `metadata?: Record` + + Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. + + - `name?: string | null` + + Body param: Updated name for the environment + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaEnvironment` + + Unified Environment resource for both cloud and BYOC environments. + + - `id: string` + + Environment identifier (e.g., 'env_...') + + - `archived_at: string | null` + + RFC 3339 timestamp when environment was archived, or null if not archived + + - `config: BetaCloudConfig` + + `cloud` environment configuration. + + - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` + + Network configuration policy. + + - `BetaUnrestrictedNetwork` + + Unrestricted network access. + + - `type: "unrestricted"` + + Network policy type + + - `"unrestricted"` + + - `BetaLimitedNetwork` + + Limited network access. + + - `allow_mcp_servers: boolean` + + Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. + + - `allow_package_managers: boolean` + + Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. + + - `allowed_hosts: Array` + + Specifies domains the container can reach. + + - `type: "limited"` + + Network policy type + + - `"limited"` + + - `packages: BetaPackages` + + Package manager configuration. + + - `apt: Array` + + Ubuntu/Debian packages to install + + - `cargo: Array` + + Rust packages to install + + - `gem: Array` + + Ruby packages to install + + - `go: Array` + + Go packages to install + + - `npm: Array` + + Node.js packages to install + + - `pip: Array` + + Python packages to install + + - `type?: "packages"` + + Package configuration type + + - `"packages"` + + - `type: "cloud"` + + Environment type + + - `"cloud"` + + - `created_at: string` + + RFC 3339 timestamp when environment was created + + - `description: string` + + User-provided description for the environment + + - `metadata: Record` + + User-provided metadata key-value pairs + + - `name: string` + + Human-readable name for the environment + + - `type: "environment"` + + The type of object (always 'environment') + + - `"environment"` + + - `updated_at: string` + + RFC 3339 timestamp when environment was last updated + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaEnvironment = await client.beta.environments.update('env_011CZkZ9X2dpNyB7HsEFoRfW'); + +console.log(betaEnvironment.id); +``` diff --git a/content/en/api/typescript/beta/files.md b/content/en/api/typescript/beta/files.md index c097dc2fa..88f45a582 100644 --- a/content/en/api/typescript/beta/files.md +++ b/content/en/api/typescript/beta/files.md @@ -22,7 +22,7 @@ Upload File - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Upload File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `FileMetadata` @@ -106,6 +104,20 @@ Upload File Whether the file can be downloaded. + - `scope?: BetaFileScope | null` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```typescript @@ -146,13 +158,17 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. + - `scope_id?: string` + + Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -196,8 +212,6 @@ List Files - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `FileMetadata` @@ -236,6 +250,20 @@ List Files Whether the file can be downloaded. + - `scope?: BetaFileScope | null` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```typescript @@ -273,7 +301,7 @@ Download File - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -317,8 +345,6 @@ Download File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `unnamed_schema_1 = Response` @@ -362,7 +388,7 @@ Get File Metadata - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -406,8 +432,6 @@ Get File Metadata - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `FileMetadata` @@ -446,6 +470,20 @@ Get File Metadata Whether the file can be downloaded. + - `scope?: BetaFileScope | null` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```typescript @@ -482,7 +520,7 @@ Delete File - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -526,8 +564,6 @@ Delete File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `DeletedFile` @@ -560,6 +596,20 @@ console.log(deletedFile.id); ## Domain Types +### Beta File Scope + +- `BetaFileScope` + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Deleted File - `DeletedFile` @@ -613,3 +663,17 @@ console.log(deletedFile.id); - `downloadable?: boolean` Whether the file can be downloaded. + + - `scope?: BetaFileScope | null` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` diff --git a/content/en/api/typescript/beta/files/delete.md b/content/en/api/typescript/beta/files/delete.md index 1bb06b909..a73219021 100644 --- a/content/en/api/typescript/beta/files/delete.md +++ b/content/en/api/typescript/beta/files/delete.md @@ -20,7 +20,7 @@ Delete File - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Delete File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `DeletedFile` diff --git a/content/en/api/typescript/beta/files/download.md b/content/en/api/typescript/beta/files/download.md index 11b4a663c..1e324c3ea 100644 --- a/content/en/api/typescript/beta/files/download.md +++ b/content/en/api/typescript/beta/files/download.md @@ -20,7 +20,7 @@ Download File - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Download File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `unnamed_schema_1 = Response` diff --git a/content/en/api/typescript/beta/files/list.md b/content/en/api/typescript/beta/files/list.md index 1c91938d9..f2876b9ef 100644 --- a/content/en/api/typescript/beta/files/list.md +++ b/content/en/api/typescript/beta/files/list.md @@ -24,13 +24,17 @@ List Files Defaults to `20`. Ranges from `1` to `1000`. + - `scope_id?: string` + + Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). + - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -74,8 +78,6 @@ List Files - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `FileMetadata` @@ -114,6 +116,20 @@ List Files Whether the file can be downloaded. + - `scope?: BetaFileScope | null` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```typescript diff --git a/content/en/api/typescript/beta/files/retrieve_metadata.md b/content/en/api/typescript/beta/files/retrieve_metadata.md index 143221aa3..3d6226478 100644 --- a/content/en/api/typescript/beta/files/retrieve_metadata.md +++ b/content/en/api/typescript/beta/files/retrieve_metadata.md @@ -20,7 +20,7 @@ Get File Metadata - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Get File Metadata - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `FileMetadata` @@ -104,6 +102,20 @@ Get File Metadata Whether the file can be downloaded. + - `scope?: BetaFileScope | null` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```typescript diff --git a/content/en/api/typescript/beta/files/upload.md b/content/en/api/typescript/beta/files/upload.md index 2aa08c9d4..7ab5e3200 100644 --- a/content/en/api/typescript/beta/files/upload.md +++ b/content/en/api/typescript/beta/files/upload.md @@ -20,7 +20,7 @@ Upload File - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -64,8 +64,6 @@ Upload File - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `FileMetadata` @@ -104,6 +102,20 @@ Upload File Whether the file can be downloaded. + - `scope?: BetaFileScope | null` + + The scope of this file, indicating the context in which it was created (e.g., a session). + + - `id: string` + + The ID of the scoping resource (e.g., the session ID). + + - `type: "session"` + + The type of scope (e.g., `"session"`). + + - `"session"` + ### Example ```typescript diff --git a/content/en/api/typescript/beta/messages.md b/content/en/api/typescript/beta/messages.md index 2bd345bec..30a19b5bc 100644 --- a/content/en/api/typescript/beta/messages.md +++ b/content/en/api/typescript/beta/messages.md @@ -2603,11 +2603,15 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4678,17 +4682,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id?: string | null` - - Body param: The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -4732,8 +4732,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - - `MessageCreateParamsNonStreaming extends MessageCreateParamsBase` - `stream?: false` @@ -5677,11 +5675,15 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -8589,11 +8591,15 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -10572,7 +10578,7 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -10616,8 +10622,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageTokensCount` @@ -10645,7 +10649,7 @@ const client = new Anthropic({ const betaMessageTokensCount = await client.beta.messages.countTokens({ messages: [{ content: 'string', role: 'user' }], - model: 'claude-opus-4-6', + model: 'claude-mythos-preview', }); console.log(betaMessageTokensCount.context_management); @@ -17836,11 +17840,15 @@ console.log(betaMessageTokensCount.context_management); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -23176,11 +23184,15 @@ console.log(betaMessageTokensCount.context_management); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -24416,11 +24428,15 @@ console.log(betaMessageTokensCount.context_management); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -35554,11 +35570,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -37627,17 +37647,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id?: string | null` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -37681,8 +37697,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` @@ -37822,7 +37836,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -37866,8 +37880,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` @@ -38006,7 +38018,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -38050,8 +38062,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` @@ -38183,7 +38193,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -38227,8 +38237,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` @@ -38359,7 +38367,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -38403,8 +38411,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaDeletedMessageBatch` @@ -38461,7 +38467,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -38505,8 +38511,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatchIndividualResponse` @@ -39448,11 +39452,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -41024,11 +41032,15 @@ console.log(betaMessageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -42392,11 +42404,15 @@ console.log(betaMessageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -43722,11 +43738,15 @@ console.log(betaMessageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/typescript/beta/messages/batches.md b/content/en/api/typescript/beta/messages/batches.md index e0da020fe..3058e1aa3 100644 --- a/content/en/api/typescript/beta/messages/batches.md +++ b/content/en/api/typescript/beta/messages/batches.md @@ -2617,11 +2617,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4690,17 +4694,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id?: string | null` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -4744,8 +4744,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` @@ -4885,7 +4883,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -4929,8 +4927,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` @@ -5069,7 +5065,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -5113,8 +5109,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` @@ -5246,7 +5240,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -5290,8 +5284,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` @@ -5422,7 +5414,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -5466,8 +5458,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaDeletedMessageBatch` @@ -5524,7 +5514,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -5568,8 +5558,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatchIndividualResponse` @@ -6511,11 +6499,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -8087,11 +8079,15 @@ console.log(betaMessageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -9455,11 +9451,15 @@ console.log(betaMessageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -10785,11 +10785,15 @@ console.log(betaMessageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/typescript/beta/messages/batches/cancel.md b/content/en/api/typescript/beta/messages/batches/cancel.md index 6c502136d..08b2846fb 100644 --- a/content/en/api/typescript/beta/messages/batches/cancel.md +++ b/content/en/api/typescript/beta/messages/batches/cancel.md @@ -24,7 +24,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -68,8 +68,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` diff --git a/content/en/api/typescript/beta/messages/batches/create.md b/content/en/api/typescript/beta/messages/batches/create.md index 1001517bb..56edba284 100644 --- a/content/en/api/typescript/beta/messages/batches/create.md +++ b/content/en/api/typescript/beta/messages/batches/create.md @@ -2615,11 +2615,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4688,17 +4692,13 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id?: string | null` - - The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -4742,8 +4742,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` diff --git a/content/en/api/typescript/beta/messages/batches/delete.md b/content/en/api/typescript/beta/messages/batches/delete.md index 637b50a6e..1224b51d2 100644 --- a/content/en/api/typescript/beta/messages/batches/delete.md +++ b/content/en/api/typescript/beta/messages/batches/delete.md @@ -24,7 +24,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -68,8 +68,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaDeletedMessageBatch` diff --git a/content/en/api/typescript/beta/messages/batches/list.md b/content/en/api/typescript/beta/messages/batches/list.md index 0be19f368..53855b4cf 100644 --- a/content/en/api/typescript/beta/messages/batches/list.md +++ b/content/en/api/typescript/beta/messages/batches/list.md @@ -32,7 +32,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -76,8 +76,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` diff --git a/content/en/api/typescript/beta/messages/batches/results.md b/content/en/api/typescript/beta/messages/batches/results.md index 0d9c73e7e..3fbdb2bc6 100644 --- a/content/en/api/typescript/beta/messages/batches/results.md +++ b/content/en/api/typescript/beta/messages/batches/results.md @@ -24,7 +24,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -68,8 +68,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatchIndividualResponse` @@ -1011,11 +1009,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/typescript/beta/messages/batches/retrieve.md b/content/en/api/typescript/beta/messages/batches/retrieve.md index 15b8ade12..86ce10568 100644 --- a/content/en/api/typescript/beta/messages/batches/retrieve.md +++ b/content/en/api/typescript/beta/messages/batches/retrieve.md @@ -22,7 +22,7 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageBatch` diff --git a/content/en/api/typescript/beta/messages/count_tokens.md b/content/en/api/typescript/beta/messages/count_tokens.md index 4e13c4d0b..ad2e2aa98 100644 --- a/content/en/api/typescript/beta/messages/count_tokens.md +++ b/content/en/api/typescript/beta/messages/count_tokens.md @@ -2591,11 +2591,15 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4574,7 +4578,7 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -4618,8 +4622,6 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaMessageTokensCount` @@ -4647,7 +4649,7 @@ const client = new Anthropic({ const betaMessageTokensCount = await client.beta.messages.countTokens({ messages: [{ content: 'string', role: 'user' }], - model: 'claude-opus-4-6', + model: 'claude-mythos-preview', }); console.log(betaMessageTokensCount.context_management); diff --git a/content/en/api/typescript/beta/messages/create.md b/content/en/api/typescript/beta/messages/create.md index 04e68e15b..7e369a659 100644 --- a/content/en/api/typescript/beta/messages/create.md +++ b/content/en/api/typescript/beta/messages/create.md @@ -2601,11 +2601,15 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4676,17 +4680,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Recommended for advanced use cases only. You usually only need to use `temperature`. - - `user_profile_id?: string | null` - - Body param: The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -4730,8 +4730,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - - `MessageCreateParamsNonStreaming extends MessageCreateParamsBase` - `stream?: false` @@ -5675,11 +5673,15 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/typescript/beta/models.md b/content/en/api/typescript/beta/models.md index 9c57c027f..aad1de53c 100644 --- a/content/en/api/typescript/beta/models.md +++ b/content/en/api/typescript/beta/models.md @@ -34,7 +34,7 @@ The Models API response can be used to determine which models are available for - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -78,8 +78,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaModelInfo` @@ -303,7 +301,7 @@ The Models API response can be used to determine information about a specific mo - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -347,8 +345,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaModelInfo` diff --git a/content/en/api/typescript/beta/models/list.md b/content/en/api/typescript/beta/models/list.md index 9d859b0c8..619bac825 100644 --- a/content/en/api/typescript/beta/models/list.md +++ b/content/en/api/typescript/beta/models/list.md @@ -32,7 +32,7 @@ The Models API response can be used to determine which models are available for - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -76,8 +76,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaModelInfo` diff --git a/content/en/api/typescript/beta/models/retrieve.md b/content/en/api/typescript/beta/models/retrieve.md index 7456fda4f..1386fe8fc 100644 --- a/content/en/api/typescript/beta/models/retrieve.md +++ b/content/en/api/typescript/beta/models/retrieve.md @@ -22,7 +22,7 @@ The Models API response can be used to determine information about a specific mo - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `BetaModelInfo` diff --git a/content/en/api/typescript/beta/sessions.md b/content/en/api/typescript/beta/sessions.md new file mode 100644 index 000000000..6e79686f4 --- /dev/null +++ b/content/en/api/typescript/beta/sessions.md @@ -0,0 +1,14267 @@ +# Sessions + +## Create + +`client.beta.sessions.create(SessionCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsSession` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `params: SessionCreateParams` + + - `agent: string | BetaManagedAgentsAgentParams` + + Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `string` + + - `BetaManagedAgentsAgentParams` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: string` + + The `agent` ID. + + - `type: "agent"` + + - `"agent"` + + - `version?: number` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + + - `environment_id: string` + + Body param: ID of the `environment` defining the container configuration for this session. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata attached to the session. + + - `resources?: Array` + + Body param: Resources (e.g. repositories, files) to mount into the session's container. + + - `BetaManagedAgentsGitHubRepositoryResourceParams` + + Mount a GitHub repository into the session's container. + + - `authorization_token: string` + + GitHub authorization token used to clone the repository. + + - `type: "github_repository"` + + - `"github_repository"` + + - `url: string` + + Github URL of the repository + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `mount_path?: string | null` + + Mount path in the container. Defaults to `/workspace/`. + + - `BetaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `mount_path?: string | null` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `title?: string | null` + + Body param: Human-readable session title. + + - `vault_ids?: Array` + + Body param: Vault IDs for stored credentials the agent can use during the session. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSession = await client.beta.sessions.create({ + agent: 'agent_011CZkYpogX7uDKUyvBTophP', + environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW', +}); + +console.log(betaManagedAgentsSession.id); +``` + +## List + +`client.beta.sessions.list(SessionListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `params: SessionListParams` + + - `agent_id?: string` + + Query param: Filter sessions created with this agent ID. + + - `agent_version?: number` + + Query param: Filter by agent version. Only applies when agent_id is also set. + + - `createdAtGt?: string` + + Query param: Return sessions created after this time (exclusive). + + - `createdAtGte?: string` + + Query param: Return sessions created at or after this time (inclusive). + + - `createdAtLt?: string` + + Query param: Return sessions created before this time (exclusive). + + - `createdAtLte?: string` + + Query param: Return sessions created at or before this time (inclusive). + + - `include_archived?: boolean` + + Query param: When true, includes archived sessions. Default: false (exclude archived). + + - `limit?: number` + + Query param: Maximum number of results to return. + + - `order?: "asc" | "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `"asc"` + + - `"desc"` + + - `page?: string` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsSession of client.beta.sessions.list()) { + console.log(betaManagedAgentsSession.id); +} +``` + +## Retrieve + +`client.beta.sessions.retrieve(stringsessionID, SessionRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsSession` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `sessionID: string` + +- `params: SessionRetrieveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSession = await client.beta.sessions.retrieve( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsSession.id); +``` + +## Update + +`client.beta.sessions.update(stringsessionID, SessionUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `sessionID: string` + +- `params: SessionUpdateParams` + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + + - `title?: string | null` + + Body param: Human-readable session title. + + - `vault_ids?: Array` + + Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSession = await client.beta.sessions.update('sesn_011CZkZAtmR3yMPDzynEDxu7'); + +console.log(betaManagedAgentsSession.id); +``` + +## Delete + +`client.beta.sessions.delete(stringsessionID, SessionDeleteParamsparams?, RequestOptionsoptions?): BetaManagedAgentsDeletedSession` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `sessionID: string` + +- `params: SessionDeleteParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedSession` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeletedSession = await client.beta.sessions.delete( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsDeletedSession.id); +``` + +## Archive + +`client.beta.sessions.archive(stringsessionID, SessionArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `sessionID: string` + +- `params: SessionArchiveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSession = await client.beta.sessions.archive( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsSession.id); +``` + +## Domain Types + +### Beta Managed Agents Agent Params + +- `BetaManagedAgentsAgentParams` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: string` + + The `agent` ID. + + - `type: "agent"` + + - `"agent"` + + - `version?: number` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + +### Beta Managed Agents Branch Checkout + +- `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + +### Beta Managed Agents Cache Creation Usage + +- `BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + +### Beta Managed Agents Commit Checkout + +- `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Deleted Session + +- `BetaManagedAgentsDeletedSession` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Beta Managed Agents File Resource Params + +- `BetaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `mount_path?: string | null` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + +### Beta Managed Agents GitHub Repository Resource Params + +- `BetaManagedAgentsGitHubRepositoryResourceParams` + + Mount a GitHub repository into the session's container. + + - `authorization_token: string` + + GitHub authorization token used to clone the repository. + + - `type: "github_repository"` + + - `"github_repository"` + + - `url: string` + + Github URL of the repository + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `mount_path?: string | null` + + Mount path in the container. Defaults to `/workspace/`. + +### Beta Managed Agents Session + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Beta Managed Agents Session Agent + +- `BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + +### Beta Managed Agents Session Stats + +- `BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + +### Beta Managed Agents Session Usage + +- `BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + +# Events + +## List + +`client.beta.sessions.events.list(stringsessionID, EventListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `sessionID: string` + +- `params: EventListParams` + + - `limit?: number` + + Query param: Query parameter for limit + + - `order?: "asc" | "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"` + + - `"desc"` + + - `page?: string` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsSessionEvent of client.beta.sessions.events.list( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +)) { + console.log(betaManagedAgentsSessionEvent); +} +``` + +## Send + +`client.beta.sessions.events.send(stringsessionID, EventSendParamsparams, RequestOptionsoptions?): BetaManagedAgentsSendSessionEvents` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `sessionID: string` + +- `params: EventSendParams` + + - `events: Array` + + Body param: Events to send to the `session`. + + - `BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data?: Array` + + Sent events + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSendSessionEvents = await client.beta.sessions.events.send( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', + { + events: [ + { content: [{ text: 'Where is my order #1234?', type: 'text' }], type: 'user.message' }, + ], + }, +); + +console.log(betaManagedAgentsSendSessionEvents.data); +``` + +## Stream + +`client.beta.sessions.events.stream(stringsessionID, EventStreamParamsparams?, RequestOptionsoptions?): BetaManagedAgentsStreamSessionEvents | Stream` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `sessionID: string` + +- `params: EventStreamParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsStreamSessionEvents = await client.beta.sessions.events.stream( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsStreamSessionEvents); +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Agent Message Event + +- `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Base64 Document Source + +- `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Base64 Image Source + +- `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Billing Error + +- `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + +### Beta Managed Agents Document Block + +- `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + +### Beta Managed Agents Event Params + +- `BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams | BetaManagedAgentsUserInterruptEventParams | BetaManagedAgentsUserToolConfirmationEventParams | BetaManagedAgentsUserCustomToolResultEventParams` + + Union type for event parameters that can be sent to a session. + + - `BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents File Image Source + +- `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents Image Block + +- `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Retry Status Exhausted + +- `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + +### Beta Managed Agents Send Session Events + +- `BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data?: Array` + + Sent events + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + +### Beta Managed Agents Session Error Event + +- `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + +### Beta Managed Agents Session Event + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Stream Session Events + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Text Block + +- `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Unknown Error + +- `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + +### Beta Managed Agents URL Document Source + +- `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + +# Resources + +## Add + +`client.beta.sessions.resources.add(stringsessionID, ResourceAddParamsparams, RequestOptionsoptions?): BetaManagedAgentsFileResource` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `sessionID: string` + +- `params: ResourceAddParams` + + - `file_id: string` + + Body param: ID of a previously uploaded file. + + - `type: "file"` + + Body param + + - `"file"` + + - `mount_path?: string | null` + + Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsFileResource = await client.beta.sessions.resources.add( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', + { file_id: 'file_011CNha8iCJcU1wXNR6q4V8w', type: 'file' }, +); + +console.log(betaManagedAgentsFileResource.id); +``` + +## List + +`client.beta.sessions.resources.list(stringsessionID, ResourceListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `sessionID: string` + +- `params: ResourceListParams` + + - `limit?: number` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `page?: string` + + Query param: Opaque cursor from a previous response's next_page field. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsSessionResource of client.beta.sessions.resources.list( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +)) { + console.log(betaManagedAgentsSessionResource); +} +``` + +## Retrieve + +`client.beta.sessions.resources.retrieve(stringresourceID, ResourceRetrieveParamsparams, RequestOptionsoptions?): ResourceRetrieveResponse` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `resourceID: string` + +- `params: ResourceRetrieveParams` + + - `session_id: string` + + Path param: Path parameter session_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const resource = await client.beta.sessions.resources.retrieve('sesrsc_011CZkZBJq5dWxk9fVLNcPht', { + session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7', +}); + +console.log(resource); +``` + +## Update + +`client.beta.sessions.resources.update(stringresourceID, ResourceUpdateParamsparams, RequestOptionsoptions?): ResourceUpdateResponse` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `resourceID: string` + +- `params: ResourceUpdateParams` + + - `session_id: string` + + Path param: Path parameter session_id + + - `authorization_token: string` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const resource = await client.beta.sessions.resources.update('sesrsc_011CZkZBJq5dWxk9fVLNcPht', { + session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7', + authorization_token: 'ghp_exampletoken', +}); + +console.log(resource); +``` + +## Delete + +`client.beta.sessions.resources.delete(stringresourceID, ResourceDeleteParamsparams, RequestOptionsoptions?): BetaManagedAgentsDeleteSessionResource` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `resourceID: string` + +- `params: ResourceDeleteParams` + + - `session_id: string` + + Path param: Path parameter session_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeleteSessionResource = await client.beta.sessions.resources.delete( + 'sesrsc_011CZkZBJq5dWxk9fVLNcPht', + { session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7' }, +); + +console.log(betaManagedAgentsDeleteSessionResource.id); +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Session Resource + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Resource Retrieve Response + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Resource Update Response + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format diff --git a/content/en/api/typescript/beta/sessions/archive.md b/content/en/api/typescript/beta/sessions/archive.md new file mode 100644 index 000000000..c03911437 --- /dev/null +++ b/content/en/api/typescript/beta/sessions/archive.md @@ -0,0 +1,505 @@ +## Archive + +`client.beta.sessions.archive(stringsessionID, SessionArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}/archive` + +Archive Session + +### Parameters + +- `sessionID: string` + +- `params: SessionArchiveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSession = await client.beta.sessions.archive( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsSession.id); +``` diff --git a/content/en/api/typescript/beta/sessions/create.md b/content/en/api/typescript/beta/sessions/create.md new file mode 100644 index 000000000..f7b05d9d2 --- /dev/null +++ b/content/en/api/typescript/beta/sessions/create.md @@ -0,0 +1,606 @@ +## Create + +`client.beta.sessions.create(SessionCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsSession` + +**post** `/v1/sessions` + +Create Session + +### Parameters + +- `params: SessionCreateParams` + + - `agent: string | BetaManagedAgentsAgentParams` + + Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. + + - `string` + + - `BetaManagedAgentsAgentParams` + + Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version + + - `id: string` + + The `agent` ID. + + - `type: "agent"` + + - `"agent"` + + - `version?: number` + + The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. + + - `environment_id: string` + + Body param: ID of the `environment` defining the container configuration for this session. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata attached to the session. + + - `resources?: Array` + + Body param: Resources (e.g. repositories, files) to mount into the session's container. + + - `BetaManagedAgentsGitHubRepositoryResourceParams` + + Mount a GitHub repository into the session's container. + + - `authorization_token: string` + + GitHub authorization token used to clone the repository. + + - `type: "github_repository"` + + - `"github_repository"` + + - `url: string` + + Github URL of the repository + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + Branch or commit to check out. Defaults to the repository's default branch. + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `mount_path?: string | null` + + Mount path in the container. Defaults to `/workspace/`. + + - `BetaManagedAgentsFileResourceParams` + + Mount a file uploaded via the Files API into the session. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `mount_path?: string | null` + + Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `title?: string | null` + + Body param: Human-readable session title. + + - `vault_ids?: Array` + + Body param: Vault IDs for stored credentials the agent can use during the session. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSession = await client.beta.sessions.create({ + agent: 'agent_011CZkYpogX7uDKUyvBTophP', + environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW', +}); + +console.log(betaManagedAgentsSession.id); +``` diff --git a/content/en/api/typescript/beta/sessions/delete.md b/content/en/api/typescript/beta/sessions/delete.md new file mode 100644 index 000000000..7e143d09d --- /dev/null +++ b/content/en/api/typescript/beta/sessions/delete.md @@ -0,0 +1,91 @@ +## Delete + +`client.beta.sessions.delete(stringsessionID, SessionDeleteParamsparams?, RequestOptionsoptions?): BetaManagedAgentsDeletedSession` + +**delete** `/v1/sessions/{session_id}` + +Delete Session + +### Parameters + +- `sessionID: string` + +- `params: SessionDeleteParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedSession` + + Confirmation that a `session` has been permanently deleted. + + - `id: string` + + - `type: "session_deleted"` + + - `"session_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeletedSession = await client.beta.sessions.delete( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsDeletedSession.id); +``` diff --git a/content/en/api/typescript/beta/sessions/events.md b/content/en/api/typescript/beta/sessions/events.md new file mode 100644 index 000000000..06d21e531 --- /dev/null +++ b/content/en/api/typescript/beta/sessions/events.md @@ -0,0 +1,9647 @@ +# Events + +## List + +`client.beta.sessions.events.list(stringsessionID, EventListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `sessionID: string` + +- `params: EventListParams` + + - `limit?: number` + + Query param: Query parameter for limit + + - `order?: "asc" | "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"` + + - `"desc"` + + - `page?: string` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsSessionEvent of client.beta.sessions.events.list( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +)) { + console.log(betaManagedAgentsSessionEvent); +} +``` + +## Send + +`client.beta.sessions.events.send(stringsessionID, EventSendParamsparams, RequestOptionsoptions?): BetaManagedAgentsSendSessionEvents` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `sessionID: string` + +- `params: EventSendParams` + + - `events: Array` + + Body param: Events to send to the `session`. + + - `BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data?: Array` + + Sent events + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSendSessionEvents = await client.beta.sessions.events.send( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', + { + events: [ + { content: [{ text: 'Where is my order #1234?', type: 'text' }], type: 'user.message' }, + ], + }, +); + +console.log(betaManagedAgentsSendSessionEvents.data); +``` + +## Stream + +`client.beta.sessions.events.stream(stringsessionID, EventStreamParamsparams?, RequestOptionsoptions?): BetaManagedAgentsStreamSessionEvents | Stream` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `sessionID: string` + +- `params: EventStreamParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsStreamSessionEvents = await client.beta.sessions.events.stream( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsStreamSessionEvents); +``` + +## Domain Types + +### Beta Managed Agents Agent Custom Tool Use Event + +- `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + +### Beta Managed Agents Agent MCP Tool Result Event + +- `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent MCP Tool Use Event + +- `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Agent Message Event + +- `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + +### Beta Managed Agents Agent Thinking Event + +- `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + +### Beta Managed Agents Agent Thread Context Compacted Event + +- `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + +### Beta Managed Agents Agent Tool Result Event + +- `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents Agent Tool Use Event + +- `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + +### Beta Managed Agents Base64 Document Source + +- `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Base64 Image Source + +- `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + +### Beta Managed Agents Billing Error + +- `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + +### Beta Managed Agents Document Block + +- `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + +### Beta Managed Agents Event Params + +- `BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams | BetaManagedAgentsUserInterruptEventParams | BetaManagedAgentsUserToolConfirmationEventParams | BetaManagedAgentsUserCustomToolResultEventParams` + + Union type for event parameters that can be sent to a session. + + - `BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents File Document Source + +- `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents File Image Source + +- `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + +### Beta Managed Agents Image Block + +- `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + +### Beta Managed Agents MCP Authentication Failed Error + +- `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + +### Beta Managed Agents MCP Connection Failed Error + +- `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + +### Beta Managed Agents Model Overloaded Error + +- `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + +### Beta Managed Agents Model Rate Limited Error + +- `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + +### Beta Managed Agents Model Request Failed Error + +- `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + +### Beta Managed Agents Plain Text Document Source + +- `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Retry Status Exhausted + +- `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + +### Beta Managed Agents Retry Status Retrying + +- `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + +### Beta Managed Agents Retry Status Terminal + +- `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + +### Beta Managed Agents Send Session Events + +- `BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data?: Array` + + Sent events + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents Session Deleted Event + +- `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session End Turn + +- `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + +### Beta Managed Agents Session Error Event + +- `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + +### Beta Managed Agents Session Event + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Session Requires Action + +- `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + +### Beta Managed Agents Session Retries Exhausted + +- `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + +### Beta Managed Agents Session Status Idle Event + +- `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + +### Beta Managed Agents Session Status Rescheduled Event + +- `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + +### Beta Managed Agents Session Status Running Event + +- `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + +### Beta Managed Agents Session Status Terminated Event + +- `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + +### Beta Managed Agents Span Model Request End Event + +- `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + +### Beta Managed Agents Span Model Request Start Event + +- `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + +### Beta Managed Agents Span Model Usage + +- `BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + +### Beta Managed Agents Stream Session Events + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Beta Managed Agents Text Block + +- `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + +### Beta Managed Agents Unknown Error + +- `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + +### Beta Managed Agents URL Document Source + +- `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + +### Beta Managed Agents URL Image Source + +- `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + +### Beta Managed Agents User Custom Tool Result Event + +- `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Custom Tool Result Event Params + +- `BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + +### Beta Managed Agents User Interrupt Event + +- `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Interrupt Event Params + +- `BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + +### Beta Managed Agents User Message Event + +- `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Message Event Params + +- `BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + +### Beta Managed Agents User Tool Confirmation Event + +- `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Beta Managed Agents User Tool Confirmation Event Params + +- `BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. diff --git a/content/en/api/typescript/beta/sessions/events/list.md b/content/en/api/typescript/beta/sessions/events/list.md new file mode 100644 index 000000000..6a2d4721d --- /dev/null +++ b/content/en/api/typescript/beta/sessions/events/list.md @@ -0,0 +1,1466 @@ +## List + +`client.beta.sessions.events.list(stringsessionID, EventListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/sessions/{session_id}/events` + +List Events + +### Parameters + +- `sessionID: string` + +- `params: EventListParams` + + - `limit?: number` + + Query param: Query parameter for limit + + - `order?: "asc" | "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). + + - `"asc"` + + - `"desc"` + + - `page?: string` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Union type for all event types in a session. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsSessionEvent of client.beta.sessions.events.list( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +)) { + console.log(betaManagedAgentsSessionEvent); +} +``` diff --git a/content/en/api/typescript/beta/sessions/events/send.md b/content/en/api/typescript/beta/sessions/events/send.md new file mode 100644 index 000000000..bc55bfdb1 --- /dev/null +++ b/content/en/api/typescript/beta/sessions/events/send.md @@ -0,0 +1,826 @@ +## Send + +`client.beta.sessions.events.send(stringsessionID, EventSendParamsparams, RequestOptionsoptions?): BetaManagedAgentsSendSessionEvents` + +**post** `/v1/sessions/{session_id}/events` + +Send Events + +### Parameters + +- `sessionID: string` + +- `params: EventSendParams` + + - `events: Array` + + Body param: Events to send to the `session`. + + - `BetaManagedAgentsUserMessageEventParams` + + Parameters for sending a user message to the session. + + - `content: Array` + + Array of content blocks for the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `BetaManagedAgentsUserInterruptEventParams` + + Parameters for sending an interrupt to pause the agent. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `BetaManagedAgentsUserToolConfirmationEventParams` + + Parameters for confirming or denying a tool execution request. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `BetaManagedAgentsUserCustomToolResultEventParams` + + Parameters for providing the result of a custom tool execution. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSendSessionEvents` + + Events that were successfully sent to the session. + + - `data?: Array` + + Sent events + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSendSessionEvents = await client.beta.sessions.events.send( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', + { + events: [ + { content: [{ text: 'Where is my order #1234?', type: 'text' }], type: 'user.message' }, + ], + }, +); + +console.log(betaManagedAgentsSendSessionEvents.data); +``` diff --git a/content/en/api/typescript/beta/sessions/events/stream.md b/content/en/api/typescript/beta/sessions/events/stream.md new file mode 100644 index 000000000..d772ba967 --- /dev/null +++ b/content/en/api/typescript/beta/sessions/events/stream.md @@ -0,0 +1,1449 @@ +## Stream + +`client.beta.sessions.events.stream(stringsessionID, EventStreamParamsparams?, RequestOptionsoptions?): BetaManagedAgentsStreamSessionEvents | Stream` + +**get** `/v1/sessions/{session_id}/events/stream` + +Stream Events + +### Parameters + +- `sessionID: string` + +- `params: EventStreamParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 17 more` + + Server-sent event in the session stream. + + - `BetaManagedAgentsUserMessageEvent` + + A user message event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of content blocks comprising the user message. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `type: "user.message"` + + - `"user.message"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserInterruptEvent` + + An interrupt event that pauses agent execution and returns control to the user. + + - `id: string` + + Unique identifier for this event. + + - `type: "user.interrupt"` + + - `"user.interrupt"` + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserToolConfirmationEvent` + + A tool confirmation event that approves or denies a pending tool execution. + + - `id: string` + + Unique identifier for this event. + + - `result: "allow" | "deny"` + + UserToolConfirmationResult enum + + - `"allow"` + + - `"deny"` + + - `tool_use_id: string` + + The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.tool_confirmation"` + + - `"user.tool_confirmation"` + + - `deny_message?: string | null` + + Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsUserCustomToolResultEvent` + + Event sent by the client providing the result of a custom tool execution. + + - `id: string` + + Unique identifier for this event. + + - `custom_tool_use_id: string` + + The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. + + - `type: "user.custom_tool_result"` + + - `"user.custom_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `processed_at?: string | null` + + A timestamp in RFC 3339 format + + - `BetaManagedAgentsAgentCustomToolUseEvent` + + Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the custom tool being called. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.custom_tool_use"` + + - `"agent.custom_tool_use"` + + - `BetaManagedAgentsAgentMessageEvent` + + An agent response event in the session conversation. + + - `id: string` + + Unique identifier for this event. + + - `content: Array` + + Array of text blocks comprising the agent response. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.message"` + + - `"agent.message"` + + - `BetaManagedAgentsAgentThinkingEvent` + + Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thinking"` + + - `"agent.thinking"` + + - `BetaManagedAgentsAgentMCPToolUseEvent` + + Event emitted when the agent invokes a tool provided by an MCP server. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `mcp_server_name: string` + + Name of the MCP server providing the tool. + + - `name: string` + + Name of the MCP tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_use"` + + - `"agent.mcp_tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentMCPToolResultEvent` + + Event representing the result of an MCP tool execution. + + - `id: string` + + Unique identifier for this event. + + - `mcp_tool_use_id: string` + + The id of the `agent.mcp_tool_use` event this result corresponds to. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.mcp_tool_result"` + + - `"agent.mcp_tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentToolUseEvent` + + Event emitted when the agent invokes a built-in agent tool. + + - `id: string` + + Unique identifier for this event. + + - `input: Record` + + Input parameters for the tool call. + + - `name: string` + + Name of the agent tool being used. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.tool_use"` + + - `"agent.tool_use"` + + - `evaluated_permission?: "allow" | "ask" | "deny"` + + AgentEvaluatedPermission enum + + - `"allow"` + + - `"ask"` + + - `"deny"` + + - `BetaManagedAgentsAgentToolResultEvent` + + Event representing the result of an agent tool execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `tool_use_id: string` + + The id of the `agent.tool_use` event this result corresponds to. + + - `type: "agent.tool_result"` + + - `"agent.tool_result"` + + - `content?: Array` + + The result content returned by the tool. + + - `BetaManagedAgentsTextBlock` + + Regular text content. + + - `text: string` + + The text content. + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsImageBlock` + + Image content specified directly as base64 data or as a reference via a URL. + + - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` + + Union type for image source variants. + + - `BetaManagedAgentsBase64ImageSource` + + Base64-encoded image data. + + - `data: string` + + Base64-encoded image data. + + - `media_type: string` + + MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsURLImageSource` + + Image referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the image to fetch. + + - `BetaManagedAgentsFileImageSource` + + Image referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "image"` + + - `"image"` + + - `BetaManagedAgentsDocumentBlock` + + Document content, either specified directly as base64 data, as text, or as a reference via a URL. + + - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` + + Union type for document source variants. + + - `BetaManagedAgentsBase64DocumentSource` + + Base64-encoded document data. + + - `data: string` + + Base64-encoded document data. + + - `media_type: string` + + MIME type of the document (e.g., "application/pdf"). + + - `type: "base64"` + + - `"base64"` + + - `BetaManagedAgentsPlainTextDocumentSource` + + Plain text document content. + + - `data: string` + + The plain text content. + + - `media_type: "text/plain"` + + MIME type of the text content. Must be "text/plain". + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `BetaManagedAgentsURLDocumentSource` + + Document referenced by URL. + + - `type: "url"` + + - `"url"` + + - `url: string` + + URL of the document to fetch. + + - `BetaManagedAgentsFileDocumentSource` + + Document referenced by file ID. + + - `file_id: string` + + ID of a previously uploaded file. + + - `type: "file"` + + - `"file"` + + - `type: "document"` + + - `"document"` + + - `context?: string | null` + + Additional context about the document for the model. + + - `title?: string | null` + + The title of the document. + + - `is_error?: boolean | null` + + Whether the tool execution resulted in an error. + + - `BetaManagedAgentsAgentThreadContextCompactedEvent` + + Indicates that context compaction (summarization) occurred during the session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "agent.thread_context_compacted"` + + - `"agent.thread_context_compacted"` + + - `BetaManagedAgentsSessionErrorEvent` + + An error event indicating a problem occurred during session execution. + + - `id: string` + + Unique identifier for this event. + + - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `BetaManagedAgentsUnknownError` + + An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "unknown_error"` + + - `"unknown_error"` + + - `BetaManagedAgentsModelOverloadedError` + + The model is currently overloaded. Emitted after automatic retries are exhausted. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_overloaded_error"` + + - `"model_overloaded_error"` + + - `BetaManagedAgentsModelRateLimitedError` + + The model request was rate-limited. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_rate_limited_error"` + + - `"model_rate_limited_error"` + + - `BetaManagedAgentsModelRequestFailedError` + + A model request failed for a reason other than overload or rate-limiting. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "model_request_failed_error"` + + - `"model_request_failed_error"` + + - `BetaManagedAgentsMCPConnectionFailedError` + + Failed to connect to an MCP server. + + - `mcp_server_name: string` + + Name of the MCP server that failed to connect. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_connection_failed_error"` + + - `"mcp_connection_failed_error"` + + - `BetaManagedAgentsMCPAuthenticationFailedError` + + Authentication to an MCP server failed. + + - `mcp_server_name: string` + + Name of the MCP server that failed authentication. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "mcp_authentication_failed_error"` + + - `"mcp_authentication_failed_error"` + + - `BetaManagedAgentsBillingError` + + The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. + + - `message: string` + + Human-readable error description. + + - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` + + What the client should do next in response to this error. + + - `BetaManagedAgentsRetryStatusRetrying` + + The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. + + - `type: "retrying"` + + - `"retrying"` + + - `BetaManagedAgentsRetryStatusExhausted` + + This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. + + - `type: "exhausted"` + + - `"exhausted"` + + - `BetaManagedAgentsRetryStatusTerminal` + + The session encountered a terminal error and will transition to `terminated` state. + + - `type: "terminal"` + + - `"terminal"` + + - `type: "billing_error"` + + - `"billing_error"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.error"` + + - `"session.error"` + + - `BetaManagedAgentsSessionStatusRescheduledEvent` + + Indicates the session is recovering from an error state and is rescheduled for execution. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_rescheduled"` + + - `"session.status_rescheduled"` + + - `BetaManagedAgentsSessionStatusRunningEvent` + + Indicates the session is actively running and the agent is working. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_running"` + + - `"session.status_running"` + + - `BetaManagedAgentsSessionStatusIdleEvent` + + Indicates the agent has paused and is awaiting user input. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` + + The agent completed its turn naturally and is ready for the next user message. + + - `BetaManagedAgentsSessionEndTurn` + + The agent completed its turn naturally and is ready for the next user message. + + - `type: "end_turn"` + + - `"end_turn"` + + - `BetaManagedAgentsSessionRequiresAction` + + The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. + + - `event_ids: Array` + + The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. + + - `type: "requires_action"` + + - `"requires_action"` + + - `BetaManagedAgentsSessionRetriesExhausted` + + The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). + + - `type: "retries_exhausted"` + + - `"retries_exhausted"` + + - `type: "session.status_idle"` + + - `"session.status_idle"` + + - `BetaManagedAgentsSessionStatusTerminatedEvent` + + Indicates the session has terminated, either due to an error or completion. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.status_terminated"` + + - `"session.status_terminated"` + + - `BetaManagedAgentsSpanModelRequestStartEvent` + + Emitted when a model request is initiated by the agent. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_start"` + + - `"span.model_request_start"` + + - `BetaManagedAgentsSpanModelRequestEndEvent` + + Emitted when a model request completes. + + - `id: string` + + Unique identifier for this event. + + - `is_error: boolean | null` + + Whether the model request resulted in an error. + + - `model_request_start_id: string` + + The id of the corresponding `span.model_request_start` event. + + - `model_usage: BetaManagedAgentsSpanModelUsage` + + Token usage for a single model request. + + - `cache_creation_input_tokens: number` + + Tokens used to create prompt cache in this request. + + - `cache_read_input_tokens: number` + + Tokens read from prompt cache in this request. + + - `input_tokens: number` + + Input tokens consumed by this request. + + - `output_tokens: number` + + Output tokens generated by this request. + + - `speed?: "standard" | "fast" | null` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "span.model_request_end"` + + - `"span.model_request_end"` + + - `BetaManagedAgentsSessionDeletedEvent` + + Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. + + - `id: string` + + Unique identifier for this event. + + - `processed_at: string` + + A timestamp in RFC 3339 format + + - `type: "session.deleted"` + + - `"session.deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsStreamSessionEvents = await client.beta.sessions.events.stream( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsStreamSessionEvents); +``` diff --git a/content/en/api/typescript/beta/sessions/list.md b/content/en/api/typescript/beta/sessions/list.md new file mode 100644 index 000000000..5bd2ee341 --- /dev/null +++ b/content/en/api/typescript/beta/sessions/list.md @@ -0,0 +1,546 @@ +## List + +`client.beta.sessions.list(SessionListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/sessions` + +List Sessions + +### Parameters + +- `params: SessionListParams` + + - `agent_id?: string` + + Query param: Filter sessions created with this agent ID. + + - `agent_version?: number` + + Query param: Filter by agent version. Only applies when agent_id is also set. + + - `createdAtGt?: string` + + Query param: Return sessions created after this time (exclusive). + + - `createdAtGte?: string` + + Query param: Return sessions created at or after this time (inclusive). + + - `createdAtLt?: string` + + Query param: Return sessions created before this time (exclusive). + + - `createdAtLte?: string` + + Query param: Return sessions created at or before this time (inclusive). + + - `include_archived?: boolean` + + Query param: When true, includes archived sessions. Default: false (exclude archived). + + - `limit?: number` + + Query param: Maximum number of results to return. + + - `order?: "asc" | "desc"` + + Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). + + - `"asc"` + + - `"desc"` + + - `page?: string` + + Query param: Opaque pagination cursor from a previous response's next_page. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsSession of client.beta.sessions.list()) { + console.log(betaManagedAgentsSession.id); +} +``` diff --git a/content/en/api/typescript/beta/sessions/resources.md b/content/en/api/typescript/beta/sessions/resources.md new file mode 100644 index 000000000..9faabe149 --- /dev/null +++ b/content/en/api/typescript/beta/sessions/resources.md @@ -0,0 +1,961 @@ +# Resources + +## Add + +`client.beta.sessions.resources.add(stringsessionID, ResourceAddParamsparams, RequestOptionsoptions?): BetaManagedAgentsFileResource` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `sessionID: string` + +- `params: ResourceAddParams` + + - `file_id: string` + + Body param: ID of a previously uploaded file. + + - `type: "file"` + + Body param + + - `"file"` + + - `mount_path?: string | null` + + Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsFileResource = await client.beta.sessions.resources.add( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', + { file_id: 'file_011CNha8iCJcU1wXNR6q4V8w', type: 'file' }, +); + +console.log(betaManagedAgentsFileResource.id); +``` + +## List + +`client.beta.sessions.resources.list(stringsessionID, ResourceListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `sessionID: string` + +- `params: ResourceListParams` + + - `limit?: number` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `page?: string` + + Query param: Opaque cursor from a previous response's next_page field. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsSessionResource of client.beta.sessions.resources.list( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +)) { + console.log(betaManagedAgentsSessionResource); +} +``` + +## Retrieve + +`client.beta.sessions.resources.retrieve(stringresourceID, ResourceRetrieveParamsparams, RequestOptionsoptions?): ResourceRetrieveResponse` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `resourceID: string` + +- `params: ResourceRetrieveParams` + + - `session_id: string` + + Path param: Path parameter session_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const resource = await client.beta.sessions.resources.retrieve('sesrsc_011CZkZBJq5dWxk9fVLNcPht', { + session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7', +}); + +console.log(resource); +``` + +## Update + +`client.beta.sessions.resources.update(stringresourceID, ResourceUpdateParamsparams, RequestOptionsoptions?): ResourceUpdateResponse` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `resourceID: string` + +- `params: ResourceUpdateParams` + + - `session_id: string` + + Path param: Path parameter session_id + + - `authorization_token: string` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const resource = await client.beta.sessions.resources.update('sesrsc_011CZkZBJq5dWxk9fVLNcPht', { + session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7', + authorization_token: 'ghp_exampletoken', +}); + +console.log(resource); +``` + +## Delete + +`client.beta.sessions.resources.delete(stringresourceID, ResourceDeleteParamsparams, RequestOptionsoptions?): BetaManagedAgentsDeleteSessionResource` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `resourceID: string` + +- `params: ResourceDeleteParams` + + - `session_id: string` + + Path param: Path parameter session_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeleteSessionResource = await client.beta.sessions.resources.delete( + 'sesrsc_011CZkZBJq5dWxk9fVLNcPht', + { session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7' }, +); + +console.log(betaManagedAgentsDeleteSessionResource.id); +``` + +## Domain Types + +### Beta Managed Agents Delete Session Resource + +- `BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Beta Managed Agents File Resource + +- `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Beta Managed Agents GitHub Repository Resource + +- `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + +### Beta Managed Agents Session Resource + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Resource Retrieve Response + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Resource Update Response + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format diff --git a/content/en/api/typescript/beta/sessions/resources/add.md b/content/en/api/typescript/beta/sessions/resources/add.md new file mode 100644 index 000000000..d1027d6b4 --- /dev/null +++ b/content/en/api/typescript/beta/sessions/resources/add.md @@ -0,0 +1,116 @@ +## Add + +`client.beta.sessions.resources.add(stringsessionID, ResourceAddParamsparams, RequestOptionsoptions?): BetaManagedAgentsFileResource` + +**post** `/v1/sessions/{session_id}/resources` + +Add Session Resource + +### Parameters + +- `sessionID: string` + +- `params: ResourceAddParams` + + - `file_id: string` + + Body param: ID of a previously uploaded file. + + - `type: "file"` + + Body param + + - `"file"` + + - `mount_path?: string | null` + + Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsFileResource = await client.beta.sessions.resources.add( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', + { file_id: 'file_011CNha8iCJcU1wXNR6q4V8w', type: 'file' }, +); + +console.log(betaManagedAgentsFileResource.id); +``` diff --git a/content/en/api/typescript/beta/sessions/resources/delete.md b/content/en/api/typescript/beta/sessions/resources/delete.md new file mode 100644 index 000000000..262526aab --- /dev/null +++ b/content/en/api/typescript/beta/sessions/resources/delete.md @@ -0,0 +1,96 @@ +## Delete + +`client.beta.sessions.resources.delete(stringresourceID, ResourceDeleteParamsparams, RequestOptionsoptions?): BetaManagedAgentsDeleteSessionResource` + +**delete** `/v1/sessions/{session_id}/resources/{resource_id}` + +Delete Session Resource + +### Parameters + +- `resourceID: string` + +- `params: ResourceDeleteParams` + + - `session_id: string` + + Path param: Path parameter session_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeleteSessionResource` + + Confirmation of resource deletion. + + - `id: string` + + - `type: "session_resource_deleted"` + + - `"session_resource_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeleteSessionResource = await client.beta.sessions.resources.delete( + 'sesrsc_011CZkZBJq5dWxk9fVLNcPht', + { session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7' }, +); + +console.log(betaManagedAgentsDeleteSessionResource.id); +``` diff --git a/content/en/api/typescript/beta/sessions/resources/list.md b/content/en/api/typescript/beta/sessions/resources/list.md new file mode 100644 index 000000000..e01b5605f --- /dev/null +++ b/content/en/api/typescript/beta/sessions/resources/list.md @@ -0,0 +1,154 @@ +## List + +`client.beta.sessions.resources.list(stringsessionID, ResourceListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/sessions/{session_id}/resources` + +List Session Resources + +### Parameters + +- `sessionID: string` + +- `params: ResourceListParams` + + - `limit?: number` + + Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. + + - `page?: string` + + Query param: Opaque cursor from a previous response's next_page field. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsSessionResource of client.beta.sessions.resources.list( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +)) { + console.log(betaManagedAgentsSessionResource); +} +``` diff --git a/content/en/api/typescript/beta/sessions/resources/retrieve.md b/content/en/api/typescript/beta/sessions/resources/retrieve.md new file mode 100644 index 000000000..d4d81a99b --- /dev/null +++ b/content/en/api/typescript/beta/sessions/resources/retrieve.md @@ -0,0 +1,151 @@ +## Retrieve + +`client.beta.sessions.resources.retrieve(stringresourceID, ResourceRetrieveParamsparams, RequestOptionsoptions?): ResourceRetrieveResponse` + +**get** `/v1/sessions/{session_id}/resources/{resource_id}` + +Get Session Resource + +### Parameters + +- `resourceID: string` + +- `params: ResourceRetrieveParams` + + - `session_id: string` + + Path param: Path parameter session_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The requested session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const resource = await client.beta.sessions.resources.retrieve('sesrsc_011CZkZBJq5dWxk9fVLNcPht', { + session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7', +}); + +console.log(resource); +``` diff --git a/content/en/api/typescript/beta/sessions/resources/update.md b/content/en/api/typescript/beta/sessions/resources/update.md new file mode 100644 index 000000000..3d81bb8be --- /dev/null +++ b/content/en/api/typescript/beta/sessions/resources/update.md @@ -0,0 +1,156 @@ +## Update + +`client.beta.sessions.resources.update(stringresourceID, ResourceUpdateParamsparams, RequestOptionsoptions?): ResourceUpdateResponse` + +**post** `/v1/sessions/{session_id}/resources/{resource_id}` + +Update Session Resource + +### Parameters + +- `resourceID: string` + +- `params: ResourceUpdateParams` + + - `session_id: string` + + Path param: Path parameter session_id + + - `authorization_token: string` + + Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource` + + The updated session resource. + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const resource = await client.beta.sessions.resources.update('sesrsc_011CZkZBJq5dWxk9fVLNcPht', { + session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7', + authorization_token: 'ghp_exampletoken', +}); + +console.log(resource); +``` diff --git a/content/en/api/typescript/beta/sessions/retrieve.md b/content/en/api/typescript/beta/sessions/retrieve.md new file mode 100644 index 000000000..44a5bbdac --- /dev/null +++ b/content/en/api/typescript/beta/sessions/retrieve.md @@ -0,0 +1,505 @@ +## Retrieve + +`client.beta.sessions.retrieve(stringsessionID, SessionRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsSession` + +**get** `/v1/sessions/{session_id}` + +Get Session + +### Parameters + +- `sessionID: string` + +- `params: SessionRetrieveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSession = await client.beta.sessions.retrieve( + 'sesn_011CZkZAtmR3yMPDzynEDxu7', +); + +console.log(betaManagedAgentsSession.id); +``` diff --git a/content/en/api/typescript/beta/sessions/update.md b/content/en/api/typescript/beta/sessions/update.md new file mode 100644 index 000000000..134dd8064 --- /dev/null +++ b/content/en/api/typescript/beta/sessions/update.md @@ -0,0 +1,515 @@ +## Update + +`client.beta.sessions.update(stringsessionID, SessionUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsSession` + +**post** `/v1/sessions/{session_id}` + +Update Session + +### Parameters + +- `sessionID: string` + +- `params: SessionUpdateParams` + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. + + - `title?: string | null` + + Body param: Human-readable session title. + + - `vault_ids?: Array` + + Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsSession` + + A Managed Agents `session`. + + - `id: string` + + - `agent: BetaManagedAgentsSessionAgent` + + Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. + + - `id: string` + + - `description: string | null` + + - `mcp_servers: Array` + + - `name: string` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `model: BetaManagedAgentsModelConfig` + + Model identifier and configuration. + + - `id: BetaManagedAgentsModel` + + The model that will power your agent. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 5 more` + + - `"claude-opus-4-6"` + + Most intelligent model for building agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `(string & {})` + + - `speed?: "standard" | "fast"` + + Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. + + - `"standard"` + + - `"fast"` + + - `name: string` + + - `skills: Array` + + - `BetaManagedAgentsAnthropicSkill` + + A resolved Anthropic-managed skill. + + - `skill_id: string` + + - `type: "anthropic"` + + - `"anthropic"` + + - `version: string` + + - `BetaManagedAgentsCustomSkill` + + A resolved user-created custom skill. + + - `skill_id: string` + + - `type: "custom"` + + - `"custom"` + + - `version: string` + + - `system: string | null` + + - `tools: Array` + + - `BetaManagedAgentsAgentToolset20260401` + + - `configs: Array` + + - `enabled: boolean` + + - `name: "bash" | "edit" | "read" | 5 more` + + Built-in agent tool identifier. + + - `"bash"` + + - `"edit"` + + - `"read"` + + - `"write"` + + - `"glob"` + + - `"grep"` + + - `"web_fetch"` + + - `"web_search"` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` + + Resolved default configuration for agent tools. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `type: "agent_toolset_20260401"` + + - `"agent_toolset_20260401"` + + - `BetaManagedAgentsMCPToolset` + + - `configs: Array` + + - `enabled: boolean` + + - `name: string` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` + + Resolved default configuration for all tools from an MCP server. + + - `enabled: boolean` + + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` + + Permission policy for tool execution. + + - `BetaManagedAgentsAlwaysAllowPolicy` + + Tool calls are automatically approved without user confirmation. + + - `type: "always_allow"` + + - `"always_allow"` + + - `BetaManagedAgentsAlwaysAskPolicy` + + Tool calls require user confirmation before execution. + + - `type: "always_ask"` + + - `"always_ask"` + + - `mcp_server_name: string` + + - `type: "mcp_toolset"` + + - `"mcp_toolset"` + + - `BetaManagedAgentsCustomTool` + + A custom tool as returned in API responses. + + - `description: string` + + - `input_schema: BetaManagedAgentsCustomToolInputSchema` + + JSON Schema for custom tool input parameters. + + - `properties?: Record | null` + + JSON Schema properties defining the tool's input parameters. + + - `required?: Array` + + List of required property names. + + - `type?: "object"` + + Must be 'object' for tool input schemas. + + - `"object"` + + - `name: string` + + - `type: "custom"` + + - `"custom"` + + - `type: "agent"` + + - `"agent"` + + - `version: number` + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `environment_id: string` + + - `metadata: Record` + + - `resources: Array` + + - `BetaManagedAgentsGitHubRepositoryResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `mount_path: string` + + - `type: "github_repository"` + + - `"github_repository"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `url: string` + + - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` + + - `BetaManagedAgentsBranchCheckout` + + - `name: string` + + Branch name to check out. + + - `type: "branch"` + + - `"branch"` + + - `BetaManagedAgentsCommitCheckout` + + - `sha: string` + + Full commit SHA to check out. + + - `type: "commit"` + + - `"commit"` + + - `BetaManagedAgentsFileResource` + + - `id: string` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `file_id: string` + + - `mount_path: string` + + - `type: "file"` + + - `"file"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `stats: BetaManagedAgentsSessionStats` + + Timing statistics for a session. + + - `active_seconds?: number` + + Cumulative time in seconds the session spent in running status. Excludes idle time. + + - `duration_seconds?: number` + + Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + + - `status: "rescheduling" | "running" | "idle" | "terminated"` + + SessionStatus enum + + - `"rescheduling"` + + - `"running"` + + - `"idle"` + + - `"terminated"` + + - `title: string | null` + + - `type: "session"` + + - `"session"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `usage: BetaManagedAgentsSessionUsage` + + Cumulative token usage for a session across all turns. + + - `cache_creation?: BetaManagedAgentsCacheCreationUsage` + + Prompt-cache creation token usage broken down by cache lifetime. + + - `ephemeral_1h_input_tokens?: number` + + Tokens used to create 1-hour ephemeral cache entries. + + - `ephemeral_5m_input_tokens?: number` + + Tokens used to create 5-minute ephemeral cache entries. + + - `cache_read_input_tokens?: number` + + Total tokens read from prompt cache. + + - `input_tokens?: number` + + Total input tokens consumed across all turns. + + - `output_tokens?: number` + + Total output tokens generated across all turns. + + - `vault_ids: Array` + + Vault IDs attached to the session at creation. Empty when no vaults were supplied. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsSession = await client.beta.sessions.update('sesn_011CZkZAtmR3yMPDzynEDxu7'); + +console.log(betaManagedAgentsSession.id); +``` diff --git a/content/en/api/typescript/beta/skills.md b/content/en/api/typescript/beta/skills.md index 35c86039b..06ab8cf42 100644 --- a/content/en/api/typescript/beta/skills.md +++ b/content/en/api/typescript/beta/skills.md @@ -30,7 +30,7 @@ Create Skill - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ Create Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `SkillCreateResponse` @@ -174,7 +172,7 @@ List Skills - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -218,8 +216,6 @@ List Skills - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `SkillListResponse` @@ -304,7 +300,7 @@ Get Skill - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -348,8 +344,6 @@ Get Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `SkillRetrieveResponse` @@ -433,7 +427,7 @@ Delete Skill - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -477,8 +471,6 @@ Delete Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `SkillDeleteResponse` @@ -694,7 +686,7 @@ Create Skill Version - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -738,8 +730,6 @@ Create Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionCreateResponse` @@ -836,7 +826,7 @@ List Skill Versions - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -880,8 +870,6 @@ List Skill Versions - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionListResponse` @@ -975,7 +963,7 @@ Get Skill Version - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -1019,8 +1007,6 @@ Get Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionRetrieveResponse` @@ -1113,7 +1099,7 @@ Delete Skill Version - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -1157,8 +1143,6 @@ Delete Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionDeleteResponse` diff --git a/content/en/api/typescript/beta/skills/create.md b/content/en/api/typescript/beta/skills/create.md index 8b3cb9784..e19e7e4d7 100644 --- a/content/en/api/typescript/beta/skills/create.md +++ b/content/en/api/typescript/beta/skills/create.md @@ -28,7 +28,7 @@ Create Skill - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -72,8 +72,6 @@ Create Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `SkillCreateResponse` diff --git a/content/en/api/typescript/beta/skills/delete.md b/content/en/api/typescript/beta/skills/delete.md index 6224fd18c..d8f78b051 100644 --- a/content/en/api/typescript/beta/skills/delete.md +++ b/content/en/api/typescript/beta/skills/delete.md @@ -22,7 +22,7 @@ Delete Skill - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Delete Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `SkillDeleteResponse` diff --git a/content/en/api/typescript/beta/skills/list.md b/content/en/api/typescript/beta/skills/list.md index c20bf7698..eff888ba7 100644 --- a/content/en/api/typescript/beta/skills/list.md +++ b/content/en/api/typescript/beta/skills/list.md @@ -37,7 +37,7 @@ List Skills - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -81,8 +81,6 @@ List Skills - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `SkillListResponse` diff --git a/content/en/api/typescript/beta/skills/retrieve.md b/content/en/api/typescript/beta/skills/retrieve.md index 77a323a1e..94f0dd5a0 100644 --- a/content/en/api/typescript/beta/skills/retrieve.md +++ b/content/en/api/typescript/beta/skills/retrieve.md @@ -22,7 +22,7 @@ Get Skill - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ Get Skill - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `SkillRetrieveResponse` diff --git a/content/en/api/typescript/beta/skills/versions.md b/content/en/api/typescript/beta/skills/versions.md index 51d41beed..3f59d8b63 100644 --- a/content/en/api/typescript/beta/skills/versions.md +++ b/content/en/api/typescript/beta/skills/versions.md @@ -30,7 +30,7 @@ Create Skill Version - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -74,8 +74,6 @@ Create Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionCreateResponse` @@ -172,7 +170,7 @@ List Skill Versions - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -216,8 +214,6 @@ List Skill Versions - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionListResponse` @@ -311,7 +307,7 @@ Get Skill Version - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -355,8 +351,6 @@ Get Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionRetrieveResponse` @@ -449,7 +443,7 @@ Delete Skill Version - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -493,8 +487,6 @@ Delete Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionDeleteResponse` diff --git a/content/en/api/typescript/beta/skills/versions/create.md b/content/en/api/typescript/beta/skills/versions/create.md index 0c67a795f..989884ac6 100644 --- a/content/en/api/typescript/beta/skills/versions/create.md +++ b/content/en/api/typescript/beta/skills/versions/create.md @@ -28,7 +28,7 @@ Create Skill Version - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -72,8 +72,6 @@ Create Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionCreateResponse` diff --git a/content/en/api/typescript/beta/skills/versions/delete.md b/content/en/api/typescript/beta/skills/versions/delete.md index 5e5d517af..935dade25 100644 --- a/content/en/api/typescript/beta/skills/versions/delete.md +++ b/content/en/api/typescript/beta/skills/versions/delete.md @@ -28,7 +28,7 @@ Delete Skill Version - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -72,8 +72,6 @@ Delete Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionDeleteResponse` diff --git a/content/en/api/typescript/beta/skills/versions/list.md b/content/en/api/typescript/beta/skills/versions/list.md index ae5d1fae6..cf531f20b 100644 --- a/content/en/api/typescript/beta/skills/versions/list.md +++ b/content/en/api/typescript/beta/skills/versions/list.md @@ -32,7 +32,7 @@ List Skill Versions - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -76,8 +76,6 @@ List Skill Versions - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionListResponse` diff --git a/content/en/api/typescript/beta/skills/versions/retrieve.md b/content/en/api/typescript/beta/skills/versions/retrieve.md index 8abc41308..344a5d07c 100644 --- a/content/en/api/typescript/beta/skills/versions/retrieve.md +++ b/content/en/api/typescript/beta/skills/versions/retrieve.md @@ -28,7 +28,7 @@ Get Skill Version - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -72,8 +72,6 @@ Get Skill Version - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `VersionRetrieveResponse` diff --git a/content/en/api/typescript/beta/vaults.md b/content/en/api/typescript/beta/vaults.md new file mode 100644 index 000000000..3e84c3b8e --- /dev/null +++ b/content/en/api/typescript/beta/vaults.md @@ -0,0 +1,2680 @@ +# Vaults + +## Create + +`client.beta.vaults.create(VaultCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsVault` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `params: VaultCreateParams` + + - `display_name: string` + + Body param: Human-readable name for the vault. 1-255 characters. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata to attach to the vault. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsVault = await client.beta.vaults.create({ display_name: 'Example vault' }); + +console.log(betaManagedAgentsVault.id); +``` + +## List + +`client.beta.vaults.list(VaultListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `params: VaultListParams` + + - `include_archived?: boolean` + + Query param: Whether to include archived vaults in the results. + + - `limit?: number` + + Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination token from a previous `list_vaults` response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsVault of client.beta.vaults.list()) { + console.log(betaManagedAgentsVault.id); +} +``` + +## Retrieve + +`client.beta.vaults.retrieve(stringvaultID, VaultRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsVault` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `vaultID: string` + +- `params: VaultRetrieveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsVault = await client.beta.vaults.retrieve('vlt_011CZkZDLs7fYzm1hXNPeRjv'); + +console.log(betaManagedAgentsVault.id); +``` + +## Update + +`client.beta.vaults.update(stringvaultID, VaultUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `vaultID: string` + +- `params: VaultUpdateParams` + + - `display_name?: string | null` + + Body param: Updated human-readable name for the vault. 1-255 characters. + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsVault = await client.beta.vaults.update('vlt_011CZkZDLs7fYzm1hXNPeRjv'); + +console.log(betaManagedAgentsVault.id); +``` + +## Delete + +`client.beta.vaults.delete(stringvaultID, VaultDeleteParamsparams?, RequestOptionsoptions?): BetaManagedAgentsDeletedVault` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `vaultID: string` + +- `params: VaultDeleteParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedVault` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeletedVault = await client.beta.vaults.delete( + 'vlt_011CZkZDLs7fYzm1hXNPeRjv', +); + +console.log(betaManagedAgentsDeletedVault.id); +``` + +## Archive + +`client.beta.vaults.archive(stringvaultID, VaultArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `vaultID: string` + +- `params: VaultArchiveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsVault = await client.beta.vaults.archive('vlt_011CZkZDLs7fYzm1hXNPeRjv'); + +console.log(betaManagedAgentsVault.id); +``` + +## Domain Types + +### Beta Managed Agents Deleted Vault + +- `BetaManagedAgentsDeletedVault` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Beta Managed Agents Vault + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +# Credentials + +## Create + +`client.beta.vaults.credentials.create(stringvaultID, CredentialCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vaultID: string` + +- `params: CredentialCreateParams` + + - `auth: BetaManagedAgentsMCPOAuthCreateParams | BetaManagedAgentsStaticBearerCreateParams` + + Body param: Authentication details for creating a credential. + + - `BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshParams | null` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `display_name?: string | null` + + Body param: Human-readable name for the credential. Up to 255 characters. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata to attach to the credential. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.create( + 'vlt_011CZkZDLs7fYzm1hXNPeRjv', + { + auth: { + token: 'bearer_exampletoken', + mcp_server_url: 'https://example-server.modelcontextprotocol.io/sse', + type: 'static_bearer', + }, + }, +); + +console.log(betaManagedAgentsCredential.id); +``` + +## List + +`client.beta.vaults.credentials.list(stringvaultID, CredentialListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vaultID: string` + +- `params: CredentialListParams` + + - `include_archived?: boolean` + + Query param: Whether to include archived credentials in the results. + + - `limit?: number` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination token from a previous `list_credentials` response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsCredential of client.beta.vaults.credentials.list( + 'vlt_011CZkZDLs7fYzm1hXNPeRjv', +)) { + console.log(betaManagedAgentsCredential.id); +} +``` + +## Retrieve + +`client.beta.vaults.credentials.retrieve(stringcredentialID, CredentialRetrieveParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialRetrieveParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.retrieve( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsCredential.id); +``` + +## Update + +`client.beta.vaults.credentials.update(stringcredentialID, CredentialUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialUpdateParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `auth?: BetaManagedAgentsMCPOAuthUpdateParams | BetaManagedAgentsStaticBearerUpdateParams` + + Body param: Updated authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token?: string | null` + + Updated OAuth access token. + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshUpdateParams | null` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token?: string | null` + + Updated OAuth refresh token. + + - `scope?: string | null` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token?: string | null` + + Updated static bearer token value. + + - `display_name?: string | null` + + Body param: Updated human-readable name for the credential. 1-255 characters. + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.update( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsCredential.id); +``` + +## Delete + +`client.beta.vaults.credentials.delete(stringcredentialID, CredentialDeleteParamsparams, RequestOptionsoptions?): BetaManagedAgentsDeletedCredential` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialDeleteParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeletedCredential = await client.beta.vaults.credentials.delete( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsDeletedCredential.id); +``` + +## Archive + +`client.beta.vaults.credentials.archive(stringcredentialID, CredentialArchiveParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialArchiveParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.archive( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsCredential.id); +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshParams | null` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token?: string | null` + + Updated OAuth refresh token. + + - `scope?: string | null` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token?: string | null` + + Updated OAuth access token. + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshUpdateParams | null` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token?: string | null` + + Updated OAuth refresh token. + + - `scope?: string | null` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token?: string | null` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. diff --git a/content/en/api/typescript/beta/vaults/archive.md b/content/en/api/typescript/beta/vaults/archive.md new file mode 100644 index 000000000..72ff1b423 --- /dev/null +++ b/content/en/api/typescript/beta/vaults/archive.md @@ -0,0 +1,111 @@ +## Archive + +`client.beta.vaults.archive(stringvaultID, VaultArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}/archive` + +Archive Vault + +### Parameters + +- `vaultID: string` + +- `params: VaultArchiveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsVault = await client.beta.vaults.archive('vlt_011CZkZDLs7fYzm1hXNPeRjv'); + +console.log(betaManagedAgentsVault.id); +``` diff --git a/content/en/api/typescript/beta/vaults/create.md b/content/en/api/typescript/beta/vaults/create.md new file mode 100644 index 000000000..81b91395e --- /dev/null +++ b/content/en/api/typescript/beta/vaults/create.md @@ -0,0 +1,117 @@ +## Create + +`client.beta.vaults.create(VaultCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsVault` + +**post** `/v1/vaults` + +Create Vault + +### Parameters + +- `params: VaultCreateParams` + + - `display_name: string` + + Body param: Human-readable name for the vault. 1-255 characters. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata to attach to the vault. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsVault = await client.beta.vaults.create({ display_name: 'Example vault' }); + +console.log(betaManagedAgentsVault.id); +``` diff --git a/content/en/api/typescript/beta/vaults/credentials.md b/content/en/api/typescript/beta/vaults/credentials.md new file mode 100644 index 000000000..7efd42e4c --- /dev/null +++ b/content/en/api/typescript/beta/vaults/credentials.md @@ -0,0 +1,1949 @@ +# Credentials + +## Create + +`client.beta.vaults.credentials.create(stringvaultID, CredentialCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vaultID: string` + +- `params: CredentialCreateParams` + + - `auth: BetaManagedAgentsMCPOAuthCreateParams | BetaManagedAgentsStaticBearerCreateParams` + + Body param: Authentication details for creating a credential. + + - `BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshParams | null` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `display_name?: string | null` + + Body param: Human-readable name for the credential. Up to 255 characters. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata to attach to the credential. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.create( + 'vlt_011CZkZDLs7fYzm1hXNPeRjv', + { + auth: { + token: 'bearer_exampletoken', + mcp_server_url: 'https://example-server.modelcontextprotocol.io/sse', + type: 'static_bearer', + }, + }, +); + +console.log(betaManagedAgentsCredential.id); +``` + +## List + +`client.beta.vaults.credentials.list(stringvaultID, CredentialListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vaultID: string` + +- `params: CredentialListParams` + + - `include_archived?: boolean` + + Query param: Whether to include archived credentials in the results. + + - `limit?: number` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination token from a previous `list_credentials` response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsCredential of client.beta.vaults.credentials.list( + 'vlt_011CZkZDLs7fYzm1hXNPeRjv', +)) { + console.log(betaManagedAgentsCredential.id); +} +``` + +## Retrieve + +`client.beta.vaults.credentials.retrieve(stringcredentialID, CredentialRetrieveParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialRetrieveParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.retrieve( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsCredential.id); +``` + +## Update + +`client.beta.vaults.credentials.update(stringcredentialID, CredentialUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialUpdateParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `auth?: BetaManagedAgentsMCPOAuthUpdateParams | BetaManagedAgentsStaticBearerUpdateParams` + + Body param: Updated authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token?: string | null` + + Updated OAuth access token. + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshUpdateParams | null` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token?: string | null` + + Updated OAuth refresh token. + + - `scope?: string | null` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token?: string | null` + + Updated static bearer token value. + + - `display_name?: string | null` + + Body param: Updated human-readable name for the credential. 1-255 characters. + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.update( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsCredential.id); +``` + +## Delete + +`client.beta.vaults.credentials.delete(stringcredentialID, CredentialDeleteParamsparams, RequestOptionsoptions?): BetaManagedAgentsDeletedCredential` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialDeleteParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeletedCredential = await client.beta.vaults.credentials.delete( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsDeletedCredential.id); +``` + +## Archive + +`client.beta.vaults.credentials.archive(stringcredentialID, CredentialArchiveParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialArchiveParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.archive( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsCredential.id); +``` + +## Domain Types + +### Beta Managed Agents Credential + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Beta Managed Agents Deleted Credential + +- `BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Beta Managed Agents MCP OAuth Auth Response + +- `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Create Params + +- `BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshParams | null` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Params + +- `BetaManagedAgentsMCPOAuthRefreshParams` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Response + +- `BetaManagedAgentsMCPOAuthRefreshResponse` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + +### Beta Managed Agents MCP OAuth Refresh Update Params + +- `BetaManagedAgentsMCPOAuthRefreshUpdateParams` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token?: string | null` + + Updated OAuth refresh token. + + - `scope?: string | null` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + +### Beta Managed Agents MCP OAuth Update Params + +- `BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token?: string | null` + + Updated OAuth access token. + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshUpdateParams | null` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token?: string | null` + + Updated OAuth refresh token. + + - `scope?: string | null` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + +### Beta Managed Agents Static Bearer Auth Response + +- `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Create Params + +- `BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + +### Beta Managed Agents Static Bearer Update Params + +- `BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token?: string | null` + + Updated static bearer token value. + +### Beta Managed Agents Token Endpoint Auth Basic Param + +- `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Response + +- `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + +### Beta Managed Agents Token Endpoint Auth Basic Update Param + +- `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + +### Beta Managed Agents Token Endpoint Auth None Param + +- `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth None Response + +- `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + +### Beta Managed Agents Token Endpoint Auth Post Param + +- `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Response + +- `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + +### Beta Managed Agents Token Endpoint Auth Post Update Param + +- `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. diff --git a/content/en/api/typescript/beta/vaults/credentials/archive.md b/content/en/api/typescript/beta/vaults/credentials/archive.md new file mode 100644 index 000000000..27702fde4 --- /dev/null +++ b/content/en/api/typescript/beta/vaults/credentials/archive.md @@ -0,0 +1,202 @@ +## Archive + +`client.beta.vaults.credentials.archive(stringcredentialID, CredentialArchiveParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` + +Archive Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialArchiveParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.archive( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsCredential.id); +``` diff --git a/content/en/api/typescript/beta/vaults/credentials/create.md b/content/en/api/typescript/beta/vaults/credentials/create.md new file mode 100644 index 000000000..bede279e2 --- /dev/null +++ b/content/en/api/typescript/beta/vaults/credentials/create.md @@ -0,0 +1,312 @@ +## Create + +`client.beta.vaults.credentials.create(stringvaultID, CredentialCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials` + +Create Credential + +### Parameters + +- `vaultID: string` + +- `params: CredentialCreateParams` + + - `auth: BetaManagedAgentsMCPOAuthCreateParams | BetaManagedAgentsStaticBearerCreateParams` + + Body param: Authentication details for creating a credential. + + - `BetaManagedAgentsMCPOAuthCreateParams` + + Parameters for creating an MCP OAuth credential. + + - `access_token: string` + + OAuth access token. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshParams | null` + + OAuth refresh token parameters for creating a credential with refresh support. + + - `client_id: string` + + OAuth client ID. + + - `refresh_token: string` + + OAuth refresh token. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneParam` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicParam` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostParam` + + Token endpoint uses POST body authentication with client credentials. + + - `client_secret: string` + + OAuth client secret. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerCreateParams` + + Parameters for creating a static bearer token credential. + + - `token: string` + + Static bearer token value. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `display_name?: string | null` + + Body param: Human-readable name for the credential. Up to 255 characters. + + - `metadata?: Record` + + Body param: Arbitrary key-value metadata to attach to the credential. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.create( + 'vlt_011CZkZDLs7fYzm1hXNPeRjv', + { + auth: { + token: 'bearer_exampletoken', + mcp_server_url: 'https://example-server.modelcontextprotocol.io/sse', + type: 'static_bearer', + }, + }, +); + +console.log(betaManagedAgentsCredential.id); +``` diff --git a/content/en/api/typescript/beta/vaults/credentials/delete.md b/content/en/api/typescript/beta/vaults/credentials/delete.md new file mode 100644 index 000000000..4b56412da --- /dev/null +++ b/content/en/api/typescript/beta/vaults/credentials/delete.md @@ -0,0 +1,98 @@ +## Delete + +`client.beta.vaults.credentials.delete(stringcredentialID, CredentialDeleteParamsparams, RequestOptionsoptions?): BetaManagedAgentsDeletedCredential` + +**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Delete Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialDeleteParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedCredential` + + Confirmation of a deleted credential. + + - `id: string` + + Unique identifier of the deleted credential. + + - `type: "vault_credential_deleted"` + + - `"vault_credential_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeletedCredential = await client.beta.vaults.credentials.delete( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsDeletedCredential.id); +``` diff --git a/content/en/api/typescript/beta/vaults/credentials/list.md b/content/en/api/typescript/beta/vaults/credentials/list.md new file mode 100644 index 000000000..72d472521 --- /dev/null +++ b/content/en/api/typescript/beta/vaults/credentials/list.md @@ -0,0 +1,210 @@ +## List + +`client.beta.vaults.credentials.list(stringvaultID, CredentialListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/vaults/{vault_id}/credentials` + +List Credentials + +### Parameters + +- `vaultID: string` + +- `params: CredentialListParams` + + - `include_archived?: boolean` + + Query param: Whether to include archived credentials in the results. + + - `limit?: number` + + Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination token from a previous `list_credentials` response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsCredential of client.beta.vaults.credentials.list( + 'vlt_011CZkZDLs7fYzm1hXNPeRjv', +)) { + console.log(betaManagedAgentsCredential.id); +} +``` diff --git a/content/en/api/typescript/beta/vaults/credentials/retrieve.md b/content/en/api/typescript/beta/vaults/credentials/retrieve.md new file mode 100644 index 000000000..4407cef24 --- /dev/null +++ b/content/en/api/typescript/beta/vaults/credentials/retrieve.md @@ -0,0 +1,202 @@ +## Retrieve + +`client.beta.vaults.credentials.retrieve(stringcredentialID, CredentialRetrieveParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**get** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Get Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialRetrieveParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.retrieve( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsCredential.id); +``` diff --git a/content/en/api/typescript/beta/vaults/credentials/update.md b/content/en/api/typescript/beta/vaults/credentials/update.md new file mode 100644 index 000000000..459b6be71 --- /dev/null +++ b/content/en/api/typescript/beta/vaults/credentials/update.md @@ -0,0 +1,282 @@ +## Update + +`client.beta.vaults.credentials.update(stringcredentialID, CredentialUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` + +**post** `/v1/vaults/{vault_id}/credentials/{credential_id}` + +Update Credential + +### Parameters + +- `credentialID: string` + +- `params: CredentialUpdateParams` + + - `vault_id: string` + + Path param: Path parameter vault_id + + - `auth?: BetaManagedAgentsMCPOAuthUpdateParams | BetaManagedAgentsStaticBearerUpdateParams` + + Body param: Updated authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthUpdateParams` + + Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `access_token?: string | null` + + Updated OAuth access token. + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshUpdateParams | null` + + Parameters for updating OAuth refresh token configuration. + + - `refresh_token?: string | null` + + Updated OAuth refresh token. + + - `scope?: string | null` + + Updated OAuth scope for the refresh request. + + - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` + + Updated HTTP Basic authentication parameters for the token endpoint. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` + + Updated POST body authentication parameters for the token endpoint. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `client_secret?: string | null` + + Updated OAuth client secret. + + - `BetaManagedAgentsStaticBearerUpdateParams` + + Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `token?: string | null` + + Updated static bearer token value. + + - `display_name?: string | null` + + Body param: Updated human-readable name for the credential. 1-255 characters. + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsCredential` + + A credential stored in a vault. Sensitive fields are never returned in responses. + + - `id: string` + + Unique identifier for the credential. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` + + Authentication details for a credential. + + - `BetaManagedAgentsMCPOAuthAuthResponse` + + OAuth credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "mcp_oauth"` + + - `"mcp_oauth"` + + - `expires_at?: string | null` + + A timestamp in RFC 3339 format + + - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` + + OAuth refresh token configuration returned in credential responses. + + - `client_id: string` + + OAuth client ID. + + - `token_endpoint: string` + + Token endpoint URL used to refresh the access token. + + - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint requires no client authentication. + + - `BetaManagedAgentsTokenEndpointAuthNoneResponse` + + Token endpoint requires no client authentication. + + - `type: "none"` + + - `"none"` + + - `BetaManagedAgentsTokenEndpointAuthBasicResponse` + + Token endpoint uses HTTP Basic authentication with client credentials. + + - `type: "client_secret_basic"` + + - `"client_secret_basic"` + + - `BetaManagedAgentsTokenEndpointAuthPostResponse` + + Token endpoint uses POST body authentication with client credentials. + + - `type: "client_secret_post"` + + - `"client_secret_post"` + + - `resource?: string | null` + + OAuth resource indicator. + + - `scope?: string | null` + + OAuth scope for the refresh request. + + - `BetaManagedAgentsStaticBearerAuthResponse` + + Static bearer token credential details for an MCP server. + + - `mcp_server_url: string` + + URL of the MCP server this credential authenticates against. + + - `type: "static_bearer"` + + - `"static_bearer"` + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `metadata: Record` + + Arbitrary key-value metadata attached to the credential. + + - `type: "vault_credential"` + + - `"vault_credential"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + + - `vault_id: string` + + Identifier of the vault this credential belongs to. + + - `display_name?: string | null` + + Human-readable name for the credential. + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsCredential = await client.beta.vaults.credentials.update( + 'vcrd_011CZkZEMt8gZan2iYOQfSkw', + { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, +); + +console.log(betaManagedAgentsCredential.id); +``` diff --git a/content/en/api/typescript/beta/vaults/delete.md b/content/en/api/typescript/beta/vaults/delete.md new file mode 100644 index 000000000..fcf9d5cf7 --- /dev/null +++ b/content/en/api/typescript/beta/vaults/delete.md @@ -0,0 +1,93 @@ +## Delete + +`client.beta.vaults.delete(stringvaultID, VaultDeleteParamsparams?, RequestOptionsoptions?): BetaManagedAgentsDeletedVault` + +**delete** `/v1/vaults/{vault_id}` + +Delete Vault + +### Parameters + +- `vaultID: string` + +- `params: VaultDeleteParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsDeletedVault` + + Confirmation of a deleted vault. + + - `id: string` + + Unique identifier of the deleted vault. + + - `type: "vault_deleted"` + + - `"vault_deleted"` + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsDeletedVault = await client.beta.vaults.delete( + 'vlt_011CZkZDLs7fYzm1hXNPeRjv', +); + +console.log(betaManagedAgentsDeletedVault.id); +``` diff --git a/content/en/api/typescript/beta/vaults/list.md b/content/en/api/typescript/beta/vaults/list.md new file mode 100644 index 000000000..cef9557ce --- /dev/null +++ b/content/en/api/typescript/beta/vaults/list.md @@ -0,0 +1,122 @@ +## List + +`client.beta.vaults.list(VaultListParamsparams?, RequestOptionsoptions?): PageCursor` + +**get** `/v1/vaults` + +List Vaults + +### Parameters + +- `params: VaultListParams` + + - `include_archived?: boolean` + + Query param: Whether to include archived vaults in the results. + + - `limit?: number` + + Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. + + - `page?: string` + + Query param: Opaque pagination token from a previous `list_vaults` response. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +// Automatically fetches more pages as needed. +for await (const betaManagedAgentsVault of client.beta.vaults.list()) { + console.log(betaManagedAgentsVault.id); +} +``` diff --git a/content/en/api/typescript/beta/vaults/retrieve.md b/content/en/api/typescript/beta/vaults/retrieve.md new file mode 100644 index 000000000..d990bc218 --- /dev/null +++ b/content/en/api/typescript/beta/vaults/retrieve.md @@ -0,0 +1,111 @@ +## Retrieve + +`client.beta.vaults.retrieve(stringvaultID, VaultRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsVault` + +**get** `/v1/vaults/{vault_id}` + +Get Vault + +### Parameters + +- `vaultID: string` + +- `params: VaultRetrieveParams` + + - `betas?: Array` + + Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsVault = await client.beta.vaults.retrieve('vlt_011CZkZDLs7fYzm1hXNPeRjv'); + +console.log(betaManagedAgentsVault.id); +``` diff --git a/content/en/api/typescript/beta/vaults/update.md b/content/en/api/typescript/beta/vaults/update.md new file mode 100644 index 000000000..f0657f43a --- /dev/null +++ b/content/en/api/typescript/beta/vaults/update.md @@ -0,0 +1,119 @@ +## Update + +`client.beta.vaults.update(stringvaultID, VaultUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsVault` + +**post** `/v1/vaults/{vault_id}` + +Update Vault + +### Parameters + +- `vaultID: string` + +- `params: VaultUpdateParams` + + - `display_name?: string | null` + + Body param: Updated human-readable name for the vault. 1-255 characters. + + - `metadata?: Record | null` + + Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. + + - `betas?: Array` + + Header param: Optional header to specify the beta version(s) you want to use. + + - `(string & {})` + + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + +### Returns + +- `BetaManagedAgentsVault` + + A vault that stores credentials for use by agents during sessions. + + - `id: string` + + Unique identifier for the vault. + + - `archived_at: string | null` + + A timestamp in RFC 3339 format + + - `created_at: string` + + A timestamp in RFC 3339 format + + - `display_name: string` + + Human-readable name for the vault. + + - `metadata: Record` + + Arbitrary key-value metadata attached to the vault. + + - `type: "vault"` + + - `"vault"` + + - `updated_at: string` + + A timestamp in RFC 3339 format + +### Example + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted +}); + +const betaManagedAgentsVault = await client.beta.vaults.update('vlt_011CZkZDLs7fYzm1hXNPeRjv'); + +console.log(betaManagedAgentsVault.id); +``` diff --git a/content/en/api/typescript/completions.md b/content/en/api/typescript/completions.md index c93142d1d..7edb20c9b 100644 --- a/content/en/api/typescript/completions.md +++ b/content/en/api/typescript/completions.md @@ -30,11 +30,15 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -170,7 +174,7 @@ Future models and features will not be compatible with Text Completions. See our - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -214,8 +218,6 @@ Future models and features will not be compatible with Text Completions. See our - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - - `CompletionCreateParamsNonStreaming extends CompletionCreateParamsBase` - `stream?: false` @@ -256,11 +258,15 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -348,7 +354,7 @@ const client = new Anthropic({ const completion = await client.completions.create({ max_tokens_to_sample: 256, - model: 'claude-opus-4-6', + model: 'claude-mythos-preview', prompt: '\n\nHuman: Hello, world!\n\nAssistant:', }); @@ -377,11 +383,15 @@ console.log(completion.id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/typescript/completions/create.md b/content/en/api/typescript/completions/create.md index 79ec54874..2bd1c248e 100644 --- a/content/en/api/typescript/completions/create.md +++ b/content/en/api/typescript/completions/create.md @@ -28,11 +28,15 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -168,7 +172,7 @@ Future models and features will not be compatible with Text Completions. See our - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -212,8 +216,6 @@ Future models and features will not be compatible with Text Completions. See our - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - - `CompletionCreateParamsNonStreaming extends CompletionCreateParamsBase` - `stream?: false` @@ -254,11 +256,15 @@ Future models and features will not be compatible with Text Completions. See our See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -346,7 +352,7 @@ const client = new Anthropic({ const completion = await client.completions.create({ max_tokens_to_sample: 256, - model: 'claude-opus-4-6', + model: 'claude-mythos-preview', prompt: '\n\nHuman: Hello, world!\n\nAssistant:', }); diff --git a/content/en/api/typescript/messages.md b/content/en/api/typescript/messages.md index 2d733d205..68f94e9eb 100644 --- a/content/en/api/typescript/messages.md +++ b/content/en/api/typescript/messages.md @@ -2309,11 +2309,15 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4554,11 +4558,15 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -7074,11 +7082,15 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -8537,7 +8549,7 @@ const client = new Anthropic({ const messageTokensCount = await client.messages.countTokens({ messages: [{ content: 'string', role: 'user' }], - model: 'claude-opus-4-6', + model: 'claude-mythos-preview', }); console.log(messageTokensCount.input_tokens); @@ -14233,11 +14245,15 @@ console.log(messageTokensCount.input_tokens); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -17760,17 +17776,21 @@ console.log(messageTokensCount.input_tokens); ### Model -- `Model = "claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more | (string & {})` +- `Model = "claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more | (string & {})` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -19637,11 +19657,15 @@ console.log(messageTokensCount.input_tokens); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -20569,11 +20593,15 @@ console.log(messageTokensCount.input_tokens); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -29662,11 +29690,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -32459,11 +32491,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -33725,11 +33761,15 @@ console.log(messageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -34785,11 +34825,15 @@ console.log(messageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -35807,11 +35851,15 @@ console.log(messageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/typescript/messages/batches.md b/content/en/api/typescript/messages/batches.md index 2b8ac9e1f..f4cbf7bad 100644 --- a/content/en/api/typescript/messages/batches.md +++ b/content/en/api/typescript/messages/batches.md @@ -2323,11 +2323,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -5120,11 +5124,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -6386,11 +6394,15 @@ console.log(messageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -7446,11 +7458,15 @@ console.log(messageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -8468,11 +8484,15 @@ console.log(messageBatchIndividualResponse.custom_id); See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/typescript/messages/batches/create.md b/content/en/api/typescript/messages/batches/create.md index 0798727d8..cea66b870 100644 --- a/content/en/api/typescript/messages/batches/create.md +++ b/content/en/api/typescript/messages/batches/create.md @@ -2321,11 +2321,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/typescript/messages/batches/results.md b/content/en/api/typescript/messages/batches/results.md index 191117e46..ece7b2978 100644 --- a/content/en/api/typescript/messages/batches/results.md +++ b/content/en/api/typescript/messages/batches/results.md @@ -747,11 +747,15 @@ Learn more about the Message Batches API in our [user guide](https://docs.claude See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/typescript/messages/count_tokens.md b/content/en/api/typescript/messages/count_tokens.md index dd426d2f6..ede119508 100644 --- a/content/en/api/typescript/messages/count_tokens.md +++ b/content/en/api/typescript/messages/count_tokens.md @@ -2297,11 +2297,15 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -3760,7 +3764,7 @@ const client = new Anthropic({ const messageTokensCount = await client.messages.countTokens({ messages: [{ content: 'string', role: 'user' }], - model: 'claude-opus-4-6', + model: 'claude-mythos-preview', }); console.log(messageTokensCount.input_tokens); diff --git a/content/en/api/typescript/messages/create.md b/content/en/api/typescript/messages/create.md index 76b1255d7..67ab39cf7 100644 --- a/content/en/api/typescript/messages/create.md +++ b/content/en/api/typescript/messages/create.md @@ -2307,11 +2307,15 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` @@ -4552,11 +4556,15 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `"claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5" | 12 more` + - `"claude-mythos-preview" | "claude-opus-4-6" | "claude-sonnet-4-6" | 13 more` + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` - Most intelligent model for building agents and coding + Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` diff --git a/content/en/api/typescript/models.md b/content/en/api/typescript/models.md index 6158278c5..cff7797c6 100644 --- a/content/en/api/typescript/models.md +++ b/content/en/api/typescript/models.md @@ -34,7 +34,7 @@ The Models API response can be used to determine which models are available for - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -78,8 +78,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `ModelInfo` @@ -303,7 +301,7 @@ The Models API response can be used to determine information about a specific mo - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -347,8 +345,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `ModelInfo` diff --git a/content/en/api/typescript/models/list.md b/content/en/api/typescript/models/list.md index c2a0455fb..d31c9b205 100644 --- a/content/en/api/typescript/models/list.md +++ b/content/en/api/typescript/models/list.md @@ -32,7 +32,7 @@ The Models API response can be used to determine which models are available for - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -76,8 +76,6 @@ The Models API response can be used to determine which models are available for - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `ModelInfo` diff --git a/content/en/api/typescript/models/retrieve.md b/content/en/api/typescript/models/retrieve.md index 505aba597..4ed6a72ec 100644 --- a/content/en/api/typescript/models/retrieve.md +++ b/content/en/api/typescript/models/retrieve.md @@ -22,7 +22,7 @@ The Models API response can be used to determine information about a specific mo - `(string & {})` - - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 19 more` + - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 18 more` - `"message-batches-2024-09-24"` @@ -66,8 +66,6 @@ The Models API response can be used to determine information about a specific mo - `"output-300k-2026-03-24"` - - `"user-profiles-2026-03-24"` - ### Returns - `ModelInfo` diff --git a/content/en/api/versioning.md b/content/en/api/versioning.md index 14173ef02..7e328a32f 100644 --- a/content/en/api/versioning.md +++ b/content/en/api/versioning.md @@ -4,7 +4,7 @@ When making API requests, you must send an `anthropic-version` request header. F --- -For any given API version, we will preserve: +For any given version with the Messages API, we will preserve: * Existing input parameters * Existing output parameters diff --git a/content/en/build-with-claude/adaptive-thinking.md b/content/en/build-with-claude/adaptive-thinking.md index cef064344..0b44b78ec 100644 --- a/content/en/build-with-claude/adaptive-thinking.md +++ b/content/en/build-with-claude/adaptive-thinking.md @@ -62,6 +62,19 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 16000 \ + --thinking '{type: adaptive}' \ + --message '{role: user, content: Explain why the sum of two even numbers is always even.}' \ + --transform content --format jsonl | + jq -r ' + if .type == "thinking" then "\nThinking: \(.thinking)" + elif .type == "text" then "\nResponse: \(.text)" + else empty end' +``` + ```python Python hidelines={1..2} import anthropic @@ -322,6 +335,21 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create \ + --transform 'content.0.text' --format yaml <<'YAML' +model: claude-opus-4-6 +max_tokens: 16000 +thinking: + type: adaptive +output_config: + effort: medium +messages: + - role: user + content: What is the capital of France? +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -507,6 +535,14 @@ puts message.content.first.text Adaptive thinking works seamlessly with [streaming](/docs/en/build-with-claude/streaming). Thinking blocks are streamed via `thinking_delta` events just like manual thinking mode: +```bash CLI +ant messages create --stream --format jsonl \ + --model claude-opus-4-6 \ + --max-tokens 16000 \ + --thinking '{type: adaptive}' \ + --message '{role: user, content: What is the greatest common divisor of 1071 and 462?}' +``` + ```python Python hidelines={1..2} import anthropic diff --git a/content/en/build-with-claude/api-and-data-retention.md b/content/en/build-with-claude/api-and-data-retention.md index 699f03e06..480ead250 100644 --- a/content/en/build-with-claude/api-and-data-retention.md +++ b/content/en/build-with-claude/api-and-data-retention.md @@ -274,5 +274,4 @@ To request a ZDR arrangement, contact the [Anthropic sales team](https://claude. - [Prompt caching](/docs/en/build-with-claude/prompt-caching) - [Batch processing](/docs/en/build-with-claude/batch-processing) - [Files API](/docs/en/api/files-create) -- [Agent SDK Sessions](/docs/en/agent-sdk/sessions) - [Trust Center](https://trust.anthropic.com/resources) \ No newline at end of file diff --git a/content/en/build-with-claude/batch-processing.md b/content/en/build-with-claude/batch-processing.md index d906066e1..64eff0181 100644 --- a/content/en/build-with-claude/batch-processing.md +++ b/content/en/build-with-claude/batch-processing.md @@ -19,7 +19,7 @@ This feature is **not** eligible for [Zero Data Retention (ZDR)](/docs/en/build- # Message Batches API -The Message Batches API is a powerful, cost-effective way to asynchronously process large volumes of [Messages](/docs/en/api/messages) requests. This approach is well-suited to tasks that do not require immediate responses, with most batches finishing in less than 1 hour while reducing costs by 50% and increasing throughput. +The Message Batches API is a powerful, cost-effective way to asynchronously process large volumes of [Messages](/docs/en/api/messages/create) requests. This approach is well-suited to tasks that do not require immediate responses, with most batches finishing in less than 1 hour while reducing costs by 50% and increasing throughput. You can [explore the API reference directly](/docs/en/api/creating-message-batches), in addition to this guide. @@ -91,7 +91,7 @@ The Batches API offers significant cost savings. All usage is charged at 50% of A Message Batch is composed of a list of requests to create a Message. The shape of an individual request is comprised of: - A unique `custom_id` for identifying the Messages request -- A `params` object with the standard [Messages API](/docs/en/api/messages) parameters +- A `params` object with the standard [Messages API](/docs/en/api/messages/create) parameters You can [create a batch](/docs/en/api/creating-message-batches) by passing this list into the `requests` parameter: @@ -129,6 +129,26 @@ curl https://api.anthropic.com/v1/messages/batches \ }' ``` +```bash CLI +ant messages:batches create <<'YAML' +requests: + - custom_id: my-first-request + params: + model: claude-opus-4-6 + max_tokens: 1024 + messages: + - role: user + content: Hello, world + - custom_id: my-second-request + params: + model: claude-opus-4-6 + max_tokens: 1024 + messages: + - role: user + content: Hi again, friend +YAML +``` + ```python Python hidelines={1} import anthropic from anthropic.types.message_create_params import MessageCreateParamsNonStreaming @@ -411,12 +431,12 @@ In this example, two separate requests are batched together for asynchronous pro **Test your batch requests with the Messages API** -Validation of the `params` object for each message request is performed asynchronously, and validation errors are returned when processing of the entire batch has ended. You can ensure that you are building your input correctly by verifying your request shape with the [Messages API](/docs/en/api/messages) first. +Validation of the `params` object for each message request is performed asynchronously, and validation errors are returned when processing of the entire batch has ended. You can ensure that you are building your input correctly by verifying your request shape with the [Messages API](/docs/en/api/messages/create) first. When a batch is first created, the response will have a processing status of `in_progress`. -```json JSON +```json Output { "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d", "type": "message_batch", @@ -475,6 +495,32 @@ done echo "Batch $MESSAGE_BATCH_ID has finished processing" ``` +```bash CLI hidelines={2..14,19} +#!/bin/bash +MESSAGE_BATCH_ID=$(ant messages:batches create \ + --transform id --format yaml <<'YAML' +requests: + - custom_id: test-1 + params: + model: claude-opus-4-6 + max_tokens: 100 + messages: + - role: user + content: Hi +YAML +) + +until [[ $(ant messages:batches retrieve \ + --message-batch-id "$MESSAGE_BATCH_ID" \ + --transform processing_status --format yaml) == "ended" ]]; do + echo "Batch $MESSAGE_BATCH_ID is still processing..." + break + sleep 60 +done + +echo "Batch $MESSAGE_BATCH_ID has finished processing" +``` + ```python Python nocheck hidelines={1} import anthropic import time @@ -687,6 +733,11 @@ while [ "$has_more" = true ]; do done ``` +```bash CLI +# Automatically fetches more pages as needed +ant messages:batches list --limit 20 +``` + ```python Python hidelines={1..2} import anthropic @@ -855,7 +906,7 @@ curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4Z echo "Success! $custom_id" ;; "errored") - if [ "$error_type" = "invalid_request" ]; then + if [ "$error_type" = "invalid_request_error" ]; then # Request body must be fixed before re-sending request echo "Validation error: $custom_id" else @@ -872,6 +923,29 @@ curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4Z ``` +```bash CLI +ant messages:batches results \ + --message-batch-id msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \ + --transform '{custom_id,"type":result.type,"error":result.error.error.type}' \ + --format jsonl \ + | while IFS= read -r line; do + custom_id=${line#*'"custom_id":"'}; custom_id=${custom_id%%'"'*} + case "$line" in + *'"type":"succeeded"'*) + printf 'Success! %s\n' "$custom_id" ;; + *'"type":"errored"'*) + case "$line" in + *'"error":"invalid_request_error"'*) + printf 'Validation error %s\n' "$custom_id" ;; + *) + printf 'Server error %s\n' "$custom_id" ;; + esac ;; + *'"type":"expired"'*) + printf 'Request expired %s\n' "$custom_id" ;; + esac + done +``` + ```python Python nocheck hidelines={1..2} import anthropic @@ -885,7 +959,7 @@ for result in client.messages.batches.results( case "succeeded": print(f"Success! {result.custom_id}") case "errored": - if result.result.error.type == "invalid_request": + if result.result.error.error.type == "invalid_request_error": # Request body must be fixed before re-sending request print(f"Validation error {result.custom_id}") else: @@ -1132,6 +1206,23 @@ curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH --header "anthropic-version: 2023-06-01" ``` +```bash CLI hidelines={2..13} +#!/bin/bash +MESSAGE_BATCH_ID=$(ant messages:batches create \ + --transform id --format yaml <<'YAML' +requests: + - custom_id: test-1 + params: + model: claude-opus-4-6 + max_tokens: 100 + messages: + - role: user + content: Hi +YAML +) +ant messages:batches cancel --message-batch-id "$MESSAGE_BATCH_ID" +``` + ```python Python nocheck hidelines={1..2} import anthropic @@ -1242,7 +1333,7 @@ puts message_batch The response will show the batch in a `canceling` state: -```json JSON +```json Output { "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF", "type": "message_batch", @@ -1330,6 +1421,46 @@ curl https://api.anthropic.com/v1/messages/batches \ }' ``` +```bash CLI +ant messages:batches create <<'YAML' +requests: + - custom_id: my-first-request + params: + model: claude-opus-4-6 + max_tokens: 1024 + system: + - type: text + text: > + You are an AI assistant tasked with analyzing literary works. Your + goal is to provide insightful commentary on themes, characters, and + writing style. + - type: text + text: "" + cache_control: + type: ephemeral + messages: + - role: user + content: Analyze the major themes in Pride and Prejudice. + - custom_id: my-second-request + params: + model: claude-opus-4-6 + max_tokens: 1024 + system: + - type: text + text: > + You are an AI assistant tasked with analyzing literary works. Your + goal is to provide insightful commentary on themes, characters, and + writing style. + - type: text + text: "" + cache_control: + type: ephemeral + messages: + - role: user + content: Write a summary of Pride and Prejudice. +YAML +``` + ```python Python hidelines={1} import anthropic from anthropic.types.message_create_params import MessageCreateParamsNonStreaming @@ -1802,6 +1933,22 @@ curl https://api.anthropic.com/v1/messages/batches \ }' ``` +```bash CLI +ant beta:messages:batches create --beta output-300k-2026-03-24 <<'YAML' +requests: + - custom_id: long-form-request + params: + model: claude-opus-4-6 + max_tokens: 300000 + messages: + - role: user + content: >- + Write a comprehensive technical guide to building distributed + systems, covering architecture patterns, consistency models, + fault tolerance, and operational best practices. +YAML +``` + ```python Python hidelines={1} import anthropic from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming diff --git a/content/en/build-with-claude/citations.md b/content/en/build-with-claude/citations.md index 65f1d9209..5a6143f5b 100644 --- a/content/en/build-with-claude/citations.md +++ b/content/en/build-with-claude/citations.md @@ -51,6 +51,27 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +messages: + - role: user + content: + - type: document + source: + type: text + media_type: text/plain + data: The grass is green. The sky is blue. + title: My Document + context: This is a trustworthy document. + citations: + enabled: true + - type: text + text: What color is the grass and sky? +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -239,6 +260,27 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 <<'YAML' +messages: + - role: user + content: + - type: document + source: + type: text + media_type: text/plain + data: This is a very long document with thousands of words... + citations: + enabled: true + cache_control: + type: ephemeral + - type: text + text: What does this document say about API features? +YAML +``` + ```python Python hidelines={1..2} import anthropic diff --git a/content/en/build-with-claude/claude-in-microsoft-foundry.md b/content/en/build-with-claude/claude-in-microsoft-foundry.md index 3f27eb143..5137d7b92 100644 --- a/content/en/build-with-claude/claude-in-microsoft-foundry.md +++ b/content/en/build-with-claude/claude-in-microsoft-foundry.md @@ -51,7 +51,7 @@ dotnet add package Anthropic.Foundry ```kotlin -implementation("com.anthropic:anthropic-java-foundry:2.18.0") +implementation("com.anthropic:anthropic-java-foundry:2.20.0") ``` @@ -59,7 +59,7 @@ implementation("com.anthropic:anthropic-java-foundry:2.18.0") com.anthropic anthropic-java-foundry - 2.18.0 + 2.20.0 ``` @@ -149,6 +149,21 @@ curl https://{resource}.services.ai.azure.com/anthropic/v1/messages \ ``` + + +```bash CLI nocheck +# ant reads ANTHROPIC_API_KEY and sends it as x-api-key, which Foundry accepts +export ANTHROPIC_API_KEY="YOUR_AZURE_API_KEY" + +ant messages create \ + --base-url https://example-resource.services.ai.azure.com/anthropic \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --message '{role: user, content: "Hello!"}' \ + --transform content +``` + + ```python nocheck @@ -481,7 +496,7 @@ Claude Opus 4.6 and Claude Sonnet 4.6 have a [1M-token context window](/docs/en/ ## API responses -API responses from Claude on Foundry follow the standard [Claude API response format](/docs/en/api/messages). This includes the `usage` object in response bodies, which provides detailed token consumption information for your requests. The `usage` object is consistent across all platforms (first-party API, Foundry, Amazon Bedrock, and Google Vertex AI). +API responses from Claude on Foundry follow the standard [Claude API response format](/docs/en/api/messages/create). This includes the `usage` object in response bodies, which provides detailed token consumption information for your requests. The `usage` object is consistent across all platforms (first-party API, Foundry, Amazon Bedrock, and Google Vertex AI). For details on response headers specific to Foundry, see the [correlation request IDs section](#correlation-request-ids). diff --git a/content/en/build-with-claude/claude-on-amazon-bedrock.md b/content/en/build-with-claude/claude-on-amazon-bedrock.md index 10b14a741..b5bebbe31 100644 --- a/content/en/build-with-claude/claude-on-amazon-bedrock.md +++ b/content/en/build-with-claude/claude-on-amazon-bedrock.md @@ -54,14 +54,14 @@ go get github.com/anthropics/anthropic-sdk-go/bedrock ```groovy Gradle -implementation("com.anthropic:anthropic-java-bedrock:2.18.0") +implementation("com.anthropic:anthropic-java-bedrock:2.20.0") ``` ```xml Maven com.anthropic anthropic-java-bedrock - 2.18.0 + 2.20.0 ``` @@ -310,6 +310,10 @@ The following examples show how to print a list of all the Claude models availab The following examples show how to generate text from Claude on Bedrock: + ```bash CLI + # The ant CLI does not yet support Amazon Bedrock. + ``` + ```python Python nocheck from anthropic import AnthropicBedrock @@ -682,6 +686,9 @@ This applies to Claude Sonnet 4.5 and future models only. Older models (Claude S The model IDs for Claude Sonnet 4.5 and 4 already include the `global.` prefix: +```bash CLI +# The ant CLI does not yet support Amazon Bedrock. +``` ```python Python nocheck from anthropic import AnthropicBedrock @@ -813,6 +820,9 @@ message = client.messages.create( To use regional endpoints, remove the `global.` prefix from the model ID: +```bash CLI +# The ant CLI does not yet support Amazon Bedrock. +``` ```python Python nocheck from anthropic import AnthropicBedrock diff --git a/content/en/build-with-claude/claude-on-vertex-ai.md b/content/en/build-with-claude/claude-on-vertex-ai.md index c50f7d768..c10734a5f 100644 --- a/content/en/build-with-claude/claude-on-vertex-ai.md +++ b/content/en/build-with-claude/claude-on-vertex-ai.md @@ -4,7 +4,7 @@ Anthropic's Claude models are now generally available through [Vertex AI](https: --- -The Vertex API for accessing Claude is nearly-identical to the [Messages API](/docs/en/api/messages) and supports all of the same options, with two key differences: +The Vertex API for accessing Claude is nearly-identical to the [Messages API](/docs/en/api/messages/create) and supports all of the same options, with two key differences: * In Vertex, `model` is not passed in the request body. Instead, it is specified in the Google Cloud endpoint URL. * In Vertex, `anthropic_version` is passed in the request body (rather than as a header), and must be set to the value `vertex-2023-10-16`. @@ -45,14 +45,14 @@ go get github.com/anthropics/anthropic-sdk-go ```groovy Gradle -implementation("com.anthropic:anthropic-java-vertex:2.18.0") +implementation("com.anthropic:anthropic-java-vertex:2.20.0") ``` ```xml Maven com.anthropic anthropic-java-vertex - 2.18.0 + 2.20.0 ``` @@ -151,6 +151,10 @@ The following examples show how to generate text from Claude on Vertex AI: }' ``` + ```bash CLI + # The ant CLI does not yet support Vertex AI. + ``` + ```python Python nocheck from anthropic import AnthropicVertex @@ -397,6 +401,10 @@ Set the `region` parameter to `"global"` when initializing the client: +```bash CLI +# The ant CLI does not yet support Vertex AI. +``` + ```python Python nocheck from anthropic import AnthropicVertex @@ -725,6 +733,10 @@ Specify a specific region like `"us-east1"` or `"europe-west1"`: +```bash CLI +# The ant CLI does not yet support Vertex AI. +``` + ```python Python nocheck from anthropic import AnthropicVertex diff --git a/content/en/build-with-claude/compaction.md b/content/en/build-with-claude/compaction.md index ae17ef859..ec53cf666 100644 --- a/content/en/build-with-claude/compaction.md +++ b/content/en/build-with-claude/compaction.md @@ -80,6 +80,19 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant beta:messages create --beta compact-2026-01-12 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: Help me build a website +context_management: + edits: + - type: compact_20260112 +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -313,6 +326,22 @@ puts response Configure when compaction triggers using the `trigger` parameter: +```bash CLI +ant beta:messages create --beta compact-2026-01-12 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: Hello, Claude +context_management: + edits: + - type: compact_20260112 + trigger: + type: input_tokens + value: 150000 +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -528,6 +557,22 @@ You have written a partial transcript for the initial task above. Please write a You can provide custom instructions via the `instructions` parameter to replace this prompt entirely. Custom instructions don't supplement the default; they completely replace it: +```bash CLI +ant beta:messages create --beta compact-2026-01-12 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: Hello, Claude +context_management: + edits: + - type: compact_20260112 + instructions: >- + Focus on preserving code snippets, variable names, and + technical decisions. +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -743,6 +788,43 @@ Use `pause_after_compaction` to pause the API after generating the compaction su When enabled, the API returns a message with the `compaction` stop reason after generating the compaction block: +```bash CLI +ant beta:messages create --beta compact-2026-01-12 \ + --transform '{stop_reason,content}' --format jsonl <<'YAML' > resp.json +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: "Hello, Claude" +context_management: + edits: + - type: compact_20260112 + pause_after_compaction: true +YAML + +# Check if compaction triggered a pause +if grep -q '"stop_reason":"compaction"' resp.json; then + # Response contains only the compaction block + RESP=$(cat resp.json) + CONTENT="${RESP#*\"content\":}" + printf '%s' "${CONTENT%\}}" > content.json + + # Continue the request + ant beta:messages create --beta compact-2026-01-12 < /dev/null +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: "Hello, Claude" + - role: assistant + content: $(cat content.json) +context_management: + edits: + - type: compact_20260112 +YAML +fi +``` + ```python Python hidelines={1..2} import anthropic @@ -1115,7 +1197,7 @@ When compaction is triggered, the API returns a `compaction` block at the start A long-running conversation may result in multiple compactions. The last compaction block reflects the final state of the prompt, replacing content prior to it with the generated summary. -```json +```json Output { "content": [ { @@ -1135,6 +1217,37 @@ A long-running conversation may result in multiple compactions. The last compact You must pass the `compaction` block back to the API on subsequent requests to continue the conversation with the shortened prompt. The simplest approach is to append the entire response content to your messages: +```bash CLI +ant beta:messages create --beta compact-2026-01-12 \ + --transform content --format jsonl <<'YAML' > content.json +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: Hello, Claude +context_management: + edits: + - type: compact_20260112 +YAML + +# After receiving a response with a compaction block, append it as the +# assistant turn and continue the conversation +ant beta:messages create --beta compact-2026-01-12 < +```bash CLI +ant beta:messages create --stream --format jsonl \ + --beta compact-2026-01-12 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: Hello, Claude +context_management: + edits: + - type: compact_20260112 +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -1765,6 +1892,24 @@ To maximize cache hit rates, add a `cache_control` breakpoint at the end of your - Only the compaction summary needs to be written as a new cache entry +```bash CLI +ant beta:messages create --beta compact-2026-01-12 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +system: + - type: text + text: You are a helpful coding assistant... + cache_control: + type: ephemeral +messages: + - role: user + content: Hello, Claude +context_management: + edits: + - type: compact_20260112 +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -1988,7 +2133,7 @@ This approach is particularly beneficial for long system prompts, as they remain Compaction requires an additional sampling step, which contributes to rate limits and billing. The API returns detailed usage information in the response: -```json +```json Output { "usage": { "input_tokens": 23000, @@ -2028,6 +2173,30 @@ When using server tools (like web search), the compaction trigger is checked at The token counting endpoint (`/v1/messages/count_tokens`) applies existing `compaction` blocks in your prompt but does not trigger new compactions. Use it to check your effective token count after previous compactions: +```bash CLI +cat > request.yaml <<'YAML' +model: claude-opus-4-6 +messages: + - role: user + content: Hello, Claude +context_management: + edits: + - type: compact_20260112 +YAML + +CURRENT=$(ant beta:messages count-tokens \ + --beta compact-2026-01-12 \ + --transform input_tokens --format yaml < request.yaml) + +ORIGINAL=$(ant beta:messages count-tokens \ + --beta compact-2026-01-12 \ + --transform context_management.original_input_tokens \ + --format yaml < request.yaml) + +printf 'Current tokens: %s\n' "$CURRENT" +printf 'Original tokens: %s\n' "$ORIGINAL" +``` + ```python Python hidelines={1..2} import anthropic @@ -2206,6 +2375,26 @@ puts "Original tokens: #{count_response.context_management.original_input_tokens Here's a complete example of a long-running conversation with compaction: +```bash CLI +# The CLI handles individual turns; maintain the messages array in the +# calling script. See the SDK tabs for the full chat() loop. Single-turn +# request shape: +ant beta:messages create --beta compact-2026-01-12 \ + --transform 'content.#(type=="text").text' --format yaml <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: Help me build a Python web scraper +context_management: + edits: + - type: compact_20260112 + trigger: + type: input_tokens + value: 100000 +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -2528,6 +2717,27 @@ puts chat(client, messages, "Now add rate limiting and error handling") Here's an example that uses `pause_after_compaction` to preserve the prior exchange and the current user message (three messages total) verbatim instead of summarizing them: +```bash CLI +# The CLI handles individual turns; maintain the messages array in the +# calling script. See the SDK tabs for the full chat() loop with +# pause-and-preserve handling. Single-turn request shape: +ant beta:messages create --beta compact-2026-01-12 \ + --transform 'content.#(type=="text").text' --format yaml <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: Help me build a Python web scraper +context_management: + edits: + - type: compact_20260112 + trigger: + type: input_tokens + value: 100000 + pause_after_compaction: true +YAML +``` + ```python Python hidelines={1} import anthropic from typing import Any diff --git a/content/en/build-with-claude/context-editing.md b/content/en/build-with-claude/context-editing.md index d5e94e2ea..cd0d1aa10 100644 --- a/content/en/build-with-claude/context-editing.md +++ b/content/en/build-with-claude/context-editing.md @@ -102,6 +102,22 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant beta:messages create --beta context-management-2025-06-27 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: Search for recent developments in AI +tools: + - type: web_search_20250305 + name: web_search +context_management: + edits: + - type: clear_tool_uses_20250919 +YAML +``` + ```python Python response = client.beta.messages.create( model="claude-opus-4-6", @@ -349,6 +365,37 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant beta:messages create --beta context-management-2025-06-27 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: Create a simple command line calculator app using Python +tools: + - type: text_editor_20250728 + name: str_replace_based_edit_tool + max_characters: 10000 + - type: web_search_20250305 + name: web_search + max_uses: 3 +context_management: + edits: + - type: clear_tool_uses_20250919 + trigger: + type: input_tokens + value: 30000 + keep: + type: tool_uses + value: 3 + clear_at_least: + type: input_tokens + value: 5000 + exclude_tools: + - web_search +YAML +``` + ```python Python response = client.beta.messages.create( model="claude-opus-4-6", @@ -766,6 +813,25 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant beta:messages create --beta context-management-2025-06-27 <<'YAML' +model: claude-opus-4-6 +max_tokens: 16000 +messages: + - role: user + content: Hello +thinking: + type: enabled + budget_tokens: 10000 +context_management: + edits: + - type: clear_thinking_20251015 + keep: + type: thinking_turns + value: 2 +YAML +``` + ```python Python nocheck response = client.beta.messages.create( model="claude-opus-4-6", @@ -1042,6 +1108,35 @@ When using multiple strategies, the `clear_thinking_20251015` strategy must be l +```bash CLI +ant beta:messages create --beta context-management-2025-06-27 <<'YAML' +model: claude-opus-4-6 +max_tokens: 16000 +thinking: + type: enabled + budget_tokens: 10000 +messages: + - role: user + content: Hello +tools: + - type: web_search_20250305 + name: web_search +context_management: + edits: + - type: clear_thinking_20251015 + keep: + type: thinking_turns + value: 2 + - type: clear_tool_uses_20250919 + trigger: + type: input_tokens + value: 50000 + keep: + type: tool_uses + value: 5 +YAML +``` + ```python Python nocheck response = client.beta.messages.create( model="claude-opus-4-6", @@ -1364,7 +1459,7 @@ puts response You can see which context edits were applied to your request using the `context_management` response field, along with helpful statistics about the content and input tokens cleared. -```json Response +```json Output { "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF", "type": "message", @@ -1453,6 +1548,38 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ }' ``` +```bash CLI +cat > request.yaml <<'YAML' +model: claude-opus-4-6 +messages: + - role: user + content: Continue our conversation... +tools: [] +context_management: + edits: + - type: clear_tool_uses_20250919 + trigger: + type: input_tokens + value: 30000 + keep: + type: tool_uses + value: 5 +YAML + +ORIGINAL=$(ant beta:messages count-tokens \ + --beta context-management-2025-06-27 \ + --transform context_management.original_input_tokens \ + --format yaml < request.yaml) + +INPUT_TOKENS=$(ant beta:messages count-tokens \ + --beta context-management-2025-06-27 \ + --transform input_tokens --format yaml < request.yaml) + +printf 'Original tokens: %s\n' "$ORIGINAL" +printf 'After clearing: %s\n' "$INPUT_TOKENS" +printf 'Savings: %s tokens\n' "$((ORIGINAL - INPUT_TOKENS))" +``` + ```python Python nocheck response = client.beta.messages.count_tokens( model="claude-opus-4-6", @@ -1711,7 +1838,7 @@ puts "Savings: #{response.context_management.original_input_tokens - response.in -```json Response +```json Output { "input_tokens": 25000, "context_management": { @@ -1738,6 +1865,22 @@ To use both features together, enable them in your API request: +```bash CLI +ant beta:messages create --beta context-management-2025-06-27 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: Hello +tools: + - type: memory_20250818 + name: memory +context_management: + edits: + - type: clear_tool_uses_20250919 +YAML +``` + ```python Python nocheck response = client.beta.messages.create( model="claude-opus-4-6", @@ -1967,6 +2110,13 @@ When compaction is enabled, the SDK monitors token usage after each model respon Add `compaction_control` to your `tool_runner` call to enable automatic summarization when token usage exceeds the threshold. + + + +The CLI does not include a `tool_runner` helper. Use [server-side compaction](/docs/en/build-with-claude/compaction) instead, which handles compaction on Anthropic's servers without SDK-side integration. + + + ```python Python hidelines={1..10} @@ -2299,7 +2449,7 @@ When using server-side tools, the SDK may incorrectly calculate token usage, cau For example, after a web search operation, the API response might show: -```json +```json Output { "usage": { "input_tokens": 63000, diff --git a/content/en/build-with-claude/data-residency.md b/content/en/build-with-claude/data-residency.md index 11a669312..742464d4a 100644 --- a/content/en/build-with-claude/data-residency.md +++ b/content/en/build-with-claude/data-residency.md @@ -41,6 +41,15 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --inference-geo us \ + --message '{role: user, content: "Summarize the key points of this document."}' \ + --transform '{content.0.text,usage.inference_geo}' --format yaml +``` + ```python Python hidelines={1..2} import anthropic @@ -90,7 +99,7 @@ console.log(`Inference geo: ${response.usage.inference_geo}`); The response `usage` object includes an `inference_geo` field indicating where inference ran: -```json +```json Output { "usage": { "input_tokens": 25, diff --git a/content/en/build-with-claude/effort.md b/content/en/build-with-claude/effort.md index 5f8f99562..9d9ae4f3f 100644 --- a/content/en/build-with-claude/effort.md +++ b/content/en/build-with-claude/effort.md @@ -80,6 +80,18 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create --transform 'content.0.text' --format yaml <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: Analyze the trade-offs between microservices and monolithic architectures +output_config: + effort: medium +YAML +``` + ```python Python hidelines={1..2} import anthropic diff --git a/content/en/build-with-claude/extended-thinking.md b/content/en/build-with-claude/extended-thinking.md index eeca50a20..fa3175c12 100644 --- a/content/en/build-with-claude/extended-thinking.md +++ b/content/en/build-with-claude/extended-thinking.md @@ -50,7 +50,7 @@ Here's an example of the default response format: } ``` -For more information about the response format of extended thinking, see the [Messages API Reference](/docs/en/api/messages). +For more information about the response format of extended thinking, see the [Messages API Reference](/docs/en/api/messages/create). ## How to use extended thinking @@ -79,6 +79,15 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create \ + --transform content --format yaml \ + --model claude-sonnet-4-6 \ + --max-tokens 16000 \ + --thinking '{type: enabled, budget_tokens: 10000}' \ + --message '{role: user, content: Are there an infinite number of prime numbers such that n mod 4 == 3?}' +``` + ```python Python hidelines={1..2} import anthropic @@ -394,6 +403,17 @@ curl https://api.anthropic.com/v1/messages \ ``` + +```bash CLI +ant messages create \ + --model claude-sonnet-4-6 \ + --max-tokens 16000 \ + --transform content --format yaml \ + --thinking '{type: enabled, budget_tokens: 10000, display: omitted}' \ + --message '{role: user, content: "What is 27 * 453?"}' +``` + + ```python Python hidelines={1..2} import anthropic @@ -729,7 +749,7 @@ end When `display: "omitted"` is set, the response contains `thinking` blocks with an empty `thinking` field: -```json +```json Output { "content": [ { @@ -783,6 +803,14 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create --stream --format jsonl \ + --model claude-sonnet-4-6 \ + --max-tokens 16000 \ + --thinking '{type: enabled, budget_tokens: 10000}' \ + --message '{role: user, content: What is the greatest common divisor of 1071 and 462?}' +``` + ```python Python hidelines={1..2} import anthropic @@ -1128,7 +1156,7 @@ end Example streaming output: -```sse +```sse Output event: message_start data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-6", "stop_reason": null, "stop_sequence": null}} @@ -1169,7 +1197,7 @@ data: {"type": "message_stop"} When `display: "omitted"` is set, the thinking block opens, a single `signature_delta` arrives, and the block closes without any `thinking_delta` events. Text streaming begins immediately after: -```sse +```sse Output event: content_block_start data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}} @@ -1252,6 +1280,29 @@ Toggling thinking modes also invalidates prompt caching for message history. For Here's a practical example showing how to preserve thinking blocks when providing tool results: +```bash CLI +ant messages create --transform content <<'YAML' +model: claude-sonnet-4-6 +max_tokens: 16000 +thinking: + type: enabled + budget_tokens: 10000 +tools: + - name: get_weather + description: Get current weather for a location + input_schema: + type: object + properties: + location: + type: string + required: + - location +messages: + - role: user + content: "What's the weather in Paris?" +YAML +``` + ```python Python weather_tool = { "name": "get_weather", @@ -1491,7 +1542,7 @@ puts message The API response includes thinking, text, and tool_use blocks: -```json +```json Output { "content": [ { @@ -1518,6 +1569,66 @@ The API response includes thinking, text, and tool_use blocks: Now let's continue the conversation and use the tool +```bash CLI +# First turn: capture the assistant content array (thinking + tool_use, +# with signatures intact) as compact JSON. +ASSISTANT_CONTENT=$(ant messages create \ + --transform content <<'YAML' +model: claude-sonnet-4-6 +max_tokens: 16000 +thinking: + type: enabled + budget_tokens: 10000 +tools: + - name: get_weather + description: Get the current weather in a given location + input_schema: + type: object + properties: + location: + type: string + description: The city and state + required: [location] +messages: + - role: user + content: What's the weather in Paris? +YAML +) + +TOOL_USE_ID=$(printf '%s' "$ASSISTANT_CONTENT" \ + | grep -o 'toolu_[A-Za-z0-9]*') + +# Second turn: pass the captured blocks back as the assistant message. +# The thinking block MUST accompany the tool_use block. +ant messages create < +```bash CLI +# Fetch ~10 kB of Pride and Prejudice for the cached system block +curl -s https://www.gutenberg.org/cache/epub/1342/pg1342.txt \ + | head -c 10000 > pride.txt + +# Emit a request body for the given thinking budget. Once CONTENT1 +# is populated (after the first turn), the assistant reply and a +# follow-up user message are appended so the conversation grows. +build_body() { + cat <- + You are an AI assistant that is tasked with literary analysis. + Analyze the following text carefully. + - type: text + text: "@./pride.txt" + cache_control: + type: ephemeral +messages: + - role: user + content: Analyze the tone of this passage. +YAML + if [[ -n "${CONTENT1:-}" ]]; then + printf ' - role: assistant\n content: %s\n' "$CONTENT1" + printf ' - role: user\n' + printf ' content: Analyze the characters in this passage.\n' + fi +} + +# First request (budget 4000): establishes the cache. Capture usage +# and content as two jsonl lines so the reply can be fed forward. +printf 'First request - establishing cache\n' +{ + read -r USAGE1 + read -r CONTENT1 +} < <(build_body 4000 \ + | ant messages create --transform '[usage,content]' --format jsonl) +printf 'First response usage: %s\n' "$USAGE1" + +# Second request: same budget, system-prompt cache hit expected. +printf '\nSecond request - same thinking parameters (cache hit expected)\n' +USAGE2=$(build_body 4000 \ + | ant messages create --transform usage --format jsonl) +printf 'Second response usage: %s\n' "$USAGE2" + +# Third request: budget changed to 8000. The cached system prompt +# still hits; only message-block caching is invalidated. +printf '\nThird request - different thinking parameters (cache miss for messages)\n' +USAGE3=$(build_body 8000 \ + | ant messages create --transform usage --format jsonl) +printf 'Third response usage: %s\n' "$USAGE3" +``` + ```python Python hidelines={1} from anthropic import Anthropic import requests @@ -2770,6 +2940,84 @@ puts "Third response usage: #{response3.usage}"
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    +```bash CLI +# Fetch the first ~10 kB of Pride and Prejudice for the cached prefix +curl -sL 'https://www.gutenberg.org/cache/epub/1342/pg1342.txt' \ + | head -c 10000 > book.txt + +# Call 1: thinking budget 4000, writes the cache +USAGE=$(ant messages create \ + --model claude-sonnet-4-6 --max-tokens 20000 \ + --transform usage <<'YAML' +thinking: + type: enabled + budget_tokens: 4000 +messages: + - role: user + content: + - type: text + text: "@./book.txt" + cache_control: + type: ephemeral + - type: text + text: "Give a one-sentence summary of this passage." +YAML +) +printf 'Call 1 (budget 4000):\n%s\n\n' "$USAGE" + +# Call 2: same budget, conversation extended; expect cache HIT +USAGE=$(ant messages create \ + --model claude-sonnet-4-6 --max-tokens 20000 \ + --transform usage <<'YAML' +thinking: + type: enabled + budget_tokens: 4000 +messages: + - role: user + content: + - type: text + text: "@./book.txt" + cache_control: + type: ephemeral + - type: text + text: "Give a one-sentence summary of this passage." + - role: assistant + content: "It opens Pride and Prejudice with the Bennet family." + - role: user + content: "Who is the protagonist?" +YAML +) +printf 'Call 2 (budget 4000):\n%s\n\n' "$USAGE" + +# Call 3: budget changed to 8000; cache MISS even though prefix is identical +USAGE=$(ant messages create \ + --model claude-sonnet-4-6 --max-tokens 20000 \ + --transform usage <<'YAML' +thinking: + type: enabled + budget_tokens: 8000 +messages: + - role: user + content: + - type: text + text: "@./book.txt" + cache_control: + type: ephemeral + - type: text + text: "Give a one-sentence summary of this passage." + - role: assistant + content: "It opens Pride and Prejudice with the Bennet family." + - role: user + content: "Who is the protagonist?" + - role: assistant + content: "Elizabeth Bennet is the protagonist." + - role: user + content: "What era is the story set in?" +YAML +) +printf 'Call 3 (budget 8000):\n%s\n' "$USAGE" +``` + ```python Python hidelines={1} from anthropic import Anthropic import requests @@ -3575,7 +3823,7 @@ puts "Third response usage: #{response3.usage}" Here is the output of the script (you may see slightly different numbers) -```text +```text Output First request - establishing cache First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 } diff --git a/content/en/build-with-claude/fast-mode.md b/content/en/build-with-claude/fast-mode.md index ca9d9653a..2a0248a88 100644 --- a/content/en/build-with-claude/fast-mode.md +++ b/content/en/build-with-claude/fast-mode.md @@ -48,6 +48,19 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant beta:messages create \ + --beta fast-mode-2026-02-01 \ + --transform 'content.0.text' --format yaml <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +speed: fast +messages: + - role: user + content: Refactor this module to use dependency injection +YAML +``` + ```python Python nocheck hidelines={1..2} import anthropic @@ -255,6 +268,18 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant beta:messages create --beta fast-mode-2026-02-01 \ + --transform usage.speed --format yaml <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +speed: fast +messages: + - role: user + content: Hello +YAML +``` + ```python Python nocheck response = client.beta.messages.create( model="claude-opus-4-6", @@ -384,7 +409,7 @@ puts(response.usage.speed) # "fast" or "standard" ``` -```json JSON hidelines={5..8} +```json Output hidelines={5..8} { "id": "msg_01XFDUDYJgAACzvnptvVoYEL", "type": "message", @@ -420,6 +445,44 @@ Falling back from fast to standard speed will result in a [prompt cache](/docs/e Since setting `max_retries` to `0` also disables retries for other transient errors (overloaded, internal server errors), the examples below re-issue the original request with default retries for those cases. +```bash CLI +# `ant` retries 429/5xx automatically and has no per-request max_retries +# override, so on a fast-mode 429 the fallback runs after the built-in +# retries exhaust. --transform-error surfaces error.type for branching. +create_message_with_fast_fallback() { + local speed="$1" max_attempts="${2:-3}" body out + body=${3:-$(cat)} + out=$( + ant beta:messages create --beta fast-mode-2026-02-01 \ + ${speed:+--speed "$speed"} \ + --transform-error error.type --format-error yaml <<<"$body" 2>/dev/null + ) && { printf '%s\n' "$out"; return; } + case "$out" in + rate_limit_error) + if [[ -n "$speed" ]]; then + create_message_with_fast_fallback "" "$max_attempts" "$body" + return + fi ;; + overloaded_error | api_error | "") + if (( max_attempts > 1 )); then + create_message_with_fast_fallback "$speed" $((max_attempts - 1)) "$body" + return + fi ;; + esac + printf '%s\n' "${out:-connection_error}" >&2 + return 1 +} + +MESSAGE=$( + create_message_with_fast_fallback fast <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +messages: + - role: user + content: Hello +YAML +) +``` ```python Python nocheck hidelines={1..2} import anthropic diff --git a/content/en/build-with-claude/files.md b/content/en/build-with-claude/files.md index 7c2ea3ebe..44d8a427a 100644 --- a/content/en/build-with-claude/files.md +++ b/content/en/build-with-claude/files.md @@ -24,7 +24,7 @@ The Files API provides a simple create-once, use-many-times approach for working - **Upload files** to Anthropic's secure storage and receive a unique `file_id` - **Download files** that are created from skills or the code execution tool -- **Reference files** in [Messages](/docs/en/api/messages) requests using the `file_id` instead of re-uploading content +- **Reference files** in [Messages](/docs/en/api/messages/create) requests using the `file_id` instead of re-uploading content - **Manage your files** with list, retrieve, and delete operations ## How to use the Files API @@ -47,6 +47,12 @@ curl -X POST https://api.anthropic.com/v1/files \ -F "file=@/path/to/document.pdf" ```` +````bash +FILE_ID=$(ant beta:files upload \ + --file /path/to/document.pdf \ + --transform id --format yaml) +```` + ````python uploaded = client.beta.files.upload( file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"), @@ -139,7 +145,7 @@ puts file.id The response from uploading a file will include: -```json +```json Output { "id": "file_011CNha8iCJcU1wXNR6q4V8w", "type": "file", @@ -189,6 +195,22 @@ curl -X POST https://api.anthropic.com/v1/messages \ EOF ```` +````bash +ant beta:messages create --beta files-api-2025-04-14 < document.txt +# The "@./path" reference inlines the file contents directly into the field. +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --transform 'content.0.text' --format yaml <<'YAML' +messages: + - role: user + content: + - type: text + text: "Here's the document content:" + - type: text + text: "@./document.txt" + - type: text + text: "Please summarize this document." +YAML +``` + ```python Python nocheck hidelines={2..5} import pandas as pd import anthropic @@ -690,6 +731,10 @@ curl https://api.anthropic.com/v1/files \ -H "anthropic-beta: files-api-2025-04-14" ``` +```bash CLI +ant beta:files list +``` + ```python Python hidelines={1..2} import anthropic @@ -804,6 +849,11 @@ curl "https://api.anthropic.com/v1/files/$FILE_ID" \ -H "anthropic-beta: files-api-2025-04-14" ```` +````bash +ant beta:files retrieve-metadata \ + --file-id "$FILE_ID" +```` + ````python file = client.beta.files.retrieve_metadata(file_id) ```` @@ -868,6 +918,11 @@ curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \ -H "anthropic-beta: files-api-2025-04-14" ```` +````bash +ant beta:files delete \ + --file-id "$FILE_ID" +```` + ````python result = client.beta.files.delete(file_id) ```` @@ -926,6 +981,12 @@ curl -X GET "https://api.anthropic.com/v1/files/$FILE_ID/content" \ --output downloaded_file.txt ```` +````bash +ant beta:files download \ + --file-id "$FILE_ID" \ + --output downloaded_file.txt +```` + ````python file_content = client.beta.files.download(file_id) @@ -1044,7 +1105,7 @@ Common errors when using the Files API include: - **File too large (413):** File exceeds the 500 MB limit - **Storage limit exceeded (403):** Your organization has reached the 500 GB storage limit -```json +```json Output { "type": "error", "error": { diff --git a/content/en/build-with-claude/handling-stop-reasons.md b/content/en/build-with-claude/handling-stop-reasons.md index 725a701f3..1480d61b6 100644 --- a/content/en/build-with-claude/handling-stop-reasons.md +++ b/content/en/build-with-claude/handling-stop-reasons.md @@ -4,7 +4,7 @@ When you make a request to the Messages API, Claude's response includes a `stop_reason` field that indicates why the model stopped generating its response. Understanding these values is crucial for building robust applications that handle different response types appropriately. -For details about `stop_reason` in the API response, see the [Messages API reference](/docs/en/api/messages). +For details about `stop_reason` in the API response, see the [Messages API reference](/docs/en/api/messages/create). ## The stop_reason field @@ -35,7 +35,7 @@ The `stop_reason` field is part of every successful Messages API response. Unlik ### end_turn The most common stop reason. Indicates Claude finished its response naturally. -```python +```python Python from anthropic import Anthropic client = Anthropic() @@ -138,7 +138,7 @@ def handle_empty_response(client, messages): ### max_tokens Claude stopped because it reached the `max_tokens` limit specified in your request. -```python +```python Python # Request with limited tokens response = client.messages.create( model="claude-opus-4-6", @@ -158,6 +158,19 @@ If Claude's response is cut off due to hitting the `max_tokens` limit, and the t +```bash CLI nocheck +RESPONSE=$(ant messages create --max-tokens 1024 \ + --format jsonl < request.yaml) + +# Check if the response was truncated mid tool use +STOP_REASON=$(jq -r '.stop_reason' <<<"$RESPONSE") +LAST_TYPE=$(jq -r '.content[-1].type' <<<"$RESPONSE") +if [ "$STOP_REASON" = "max_tokens" ] && [ "$LAST_TYPE" = "tool_use" ]; then + # Retry with a higher max_tokens + ant messages create --max-tokens 4096 < request.yaml +fi +``` + ```python Python nocheck hidelines={1..8} import anthropic @@ -378,7 +391,7 @@ end ### stop_sequence Claude encountered one of your custom stop sequences. -```python +```python Python response = client.messages.create( model="claude-opus-4-6", max_tokens=1024, @@ -397,7 +410,7 @@ Claude is calling a tool and expects you to execute it. For most tool use implementations, we recommend using the [tool runner](/docs/en/agents-and-tools/tool-use/tool-runner) which automatically handles tool execution, result formatting, and conversation management. -```python nocheck +```python Python nocheck from anthropic import Anthropic client = Anthropic() @@ -439,7 +452,7 @@ Returned when the server-side sampling loop reaches its iteration limit while ex When this happens, the response may contain a `server_tool_use` block without a corresponding `server_tool_result`. To let Claude finish processing, continue the conversation by sending the response back as-is. -```python nocheck +```python Python nocheck response = client.messages.create( model="claude-opus-4-6", max_tokens=1024, @@ -467,7 +480,7 @@ Your application should handle `pause_turn` in any agent loop that uses server t ### refusal Claude refused to generate a response due to safety concerns. -```python +```python Python response = client.messages.create( model="claude-opus-4-6", max_tokens=1024, @@ -491,7 +504,7 @@ To learn more about refusals triggered by API safety filters for Claude Sonnet 4 ### model_context_window_exceeded Claude stopped because it reached the model's context window limit. This allows you to request the maximum possible tokens without knowing the exact input size. -```python nocheck +```python Python nocheck # Request with maximum tokens to get as much as possible response = client.messages.create( model="claude-opus-4-6", @@ -609,7 +622,7 @@ It's important to distinguish between `stop_reason` values and actual errors: - Indicate request processing failures - Response contains error details -```python +```python Python import anthropic from anthropic import Anthropic @@ -641,7 +654,7 @@ When using streaming, `stop_reason` is: - Provided in the `message_delta` event - Not provided in any other events -```python +```python Python from anthropic import Anthropic client = Anthropic() diff --git a/content/en/build-with-claude/pdf-support.md b/content/en/build-with-claude/pdf-support.md index 3de7c8aa3..b9f9ce56d 100644 --- a/content/en/build-with-claude/pdf-support.md +++ b/content/en/build-with-claude/pdf-support.md @@ -119,6 +119,21 @@ The simplest approach is to reference a PDF directly from a URL: }] }' ``` + ```bash CLI + ant messages create --transform content --format yaml <<'YAML' + model: claude-opus-4-6 + max_tokens: 1024 + messages: + - role: user + content: + - type: document + source: + type: url + url: https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf + - type: text + text: What are the key findings in this document? + YAML + ``` ```python Python hidelines={1..2} import anthropic @@ -265,6 +280,25 @@ If you need to send PDFs from your local system or when a URL isn't available: -H "anthropic-version: 2023-06-01" \ -d @request.json ``` + ```bash CLI hidelines={1..2} + cd "$(mktemp -d)" + curl -sSo document.pdf https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf + ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --transform content --format yaml <<'YAML' + messages: + - role: user + content: + - type: document + source: + type: base64 + media_type: application/pdf + data: "@./document.pdf" + - type: text + text: What are the key findings in this document? + YAML + ``` ```python Python hidelines={1} import anthropic import base64 @@ -459,6 +493,32 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI hidelines={1..2} +cd "$(mktemp -d)" +curl -sSo document.pdf https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf +# First, upload your PDF to the Files API +FILE_ID=$(ant beta:files upload \ + --file ./document.pdf \ + --transform id --format yaml) + +# Then use the returned file_id in your message +ant beta:messages create \ + --beta files-api-2025-04-14 \ + --transform content --format yaml <- + Which model has the highest human preference win rates + across each use-case? + - custom_id: my-second-request + params: + model: claude-opus-4-6 + max_tokens: 1024 + messages: + - role: user + content: + - type: document + source: + type: base64 + media_type: application/pdf + data: "@./document.pdf" + - type: text + text: Extract 5 key insights from this document. +YAML +``` ```python Python nocheck hidelines={1..5,7..13} import anthropic @@ -1066,7 +1183,7 @@ public class MessagesBatchDocumentExample { See complete API documentation for PDF support. diff --git a/content/en/build-with-claude/prompt-caching.md b/content/en/build-with-claude/prompt-caching.md index 3113b8598..332435427 100644 --- a/content/en/build-with-claude/prompt-caching.md +++ b/content/en/build-with-claude/prompt-caching.md @@ -36,6 +36,21 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create --transform usage <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +cache_control: + type: ephemeral +system: >- + You are an AI assistant tasked with analyzing literary works. Your goal is + to provide insightful commentary on themes, characters, and writing style. +messages: + - role: user + content: Analyze the major themes in Pride and Prejudice. +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -306,6 +321,23 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create --transform usage <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +cache_control: + type: ephemeral +system: You are a helpful assistant that remembers our conversation. +messages: + - role: user + content: My name is Alex. I work on machine learning. + - role: assistant + content: Nice to meet you, Alex! How can I help with your ML work today? + - role: user + content: What did I say I work on? +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -818,7 +850,7 @@ To use the extended cache, include `ttl` in the `cache_control` definition like ``` The response will include detailed cache information like the following: -```json +```json Output { "usage": { "input_tokens": 2048, @@ -909,6 +941,25 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +system: + - type: text + text: You are an AI assistant tasked with analyzing legal documents. + - type: text + text: >- + Here is the full text of a complex legal agreement: + [Insert full text of a 50-page legal agreement here] + cache_control: + type: ephemeral +messages: + - role: user + content: What are the key terms and conditions in this agreement? +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -1258,6 +1309,40 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +system: + - type: text + text: "...long system prompt" + cache_control: + type: ephemeral +messages: + - role: user + content: + - type: text + text: Hello, can you tell me more about the solar system? + - role: assistant + content: >- + Certainly! The solar system is the collection of celestial bodies that + orbit our Sun. It consists of eight planets, numerous moons, asteroids, + comets, and other objects. The planets, in order from closest to farthest + from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, + and Neptune. Each planet has its own unique characteristics and features. + Is there a specific aspect of the solar system you would like to know + more about? + - role: user + content: + - type: text + text: Good to know. + - type: text + text: Tell me more about Mars. + cache_control: + type: ephemeral +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -1720,6 +1805,94 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +tools: + - name: search_documents + description: Search through the knowledge base + input_schema: + type: object + properties: + query: + type: string + description: Search query + required: [query] + - name: get_document + description: Retrieve a specific document by ID + input_schema: + type: object + properties: + doc_id: + type: string + description: Document ID + required: [doc_id] + cache_control: + type: ephemeral +system: + - type: text + text: |- + You are a helpful research assistant with access to a document knowledge base. + + # Instructions + - Always search for relevant documents before answering + - Provide citations for your sources + - Be objective and accurate in your responses + - If multiple documents contain relevant information, synthesize them + - Acknowledge when information is not available in the knowledge base + cache_control: + type: ephemeral + - type: text + text: |- + # Knowledge Base Context + + Here are the relevant documents for this conversation: + + ## Document 1: Solar System Overview + The solar system consists of the Sun and all objects that orbit it... + + ## Document 2: Planetary Characteristics + Each planet has unique features. Mercury is the smallest planet... + + ## Document 3: Mars Exploration + Mars has been a target of exploration for decades... + + [Additional documents...] + cache_control: + type: ephemeral +messages: + - role: user + content: Can you search for information about Mars rovers? + - role: assistant + content: + - type: tool_use + id: tool_1 + name: search_documents + input: + query: Mars rovers + - role: user + content: + - type: tool_result + tool_use_id: tool_1 + content: >- + Found 3 relevant documents: Document 3 (Mars Exploration), + Document 7 (Rover Technology), Document 9 (Mission History) + - role: assistant + content: + - type: text + text: >- + I found 3 relevant documents about Mars rovers. Let me get more + details from the Mars Exploration document. + - role: user + content: + - type: text + text: Yes, please tell me about the Perseverance rover specifically. + cache_control: + type: ephemeral +YAML +``` + ```python Python hidelines={1..2} import anthropic diff --git a/content/en/build-with-claude/prompt-engineering/claude-prompting-best-practices.md b/content/en/build-with-claude/prompt-engineering/claude-prompting-best-practices.md index 18325fd13..3f8031baf 100644 --- a/content/en/build-with-claude/prompt-engineering/claude-prompting-best-practices.md +++ b/content/en/build-with-claude/prompt-engineering/claude-prompting-best-practices.md @@ -80,7 +80,7 @@ Best practices: Setting a role in the system prompt focuses Claude's behavior and tone for your use case. Even a single sentence makes a difference: -```python +```python Python import anthropic client = anthropic.Anthropic() @@ -394,7 +394,9 @@ Extended thinking adds latency and should only be used when it will meaningfully If you are migrating from [extended thinking](/docs/en/build-with-claude/extended-thinking) with `budget_tokens`, replace your thinking configuration and move budget control to `effort`: -```python Before (extended thinking, older models) nocheck +**Before (extended thinking, older models):** + +```python Python nocheck client.messages.create( model="claude-sonnet-4-5-20250929", max_tokens=64000, @@ -403,7 +405,9 @@ client.messages.create( ) ``` -```python After (adaptive thinking) nocheck +**After (adaptive thinking):** + +```python Python nocheck client.messages.create( model="claude-opus-4-6", max_tokens=64000, @@ -680,7 +684,7 @@ Claude Sonnet 4.6 defaults to an effort level of `high`, in contrast to Claude S If you're not using extended thinking on Claude Sonnet 4.5, you can continue without it on Claude Sonnet 4.6. You should explicitly set effort to the level appropriate for your use case. At `low` effort with thinking disabled, you can expect similar or better performance relative to Claude Sonnet 4.5 with no extended thinking. -```python +```python Python client.messages.create( model="claude-sonnet-4-6", max_tokens=8192, @@ -704,7 +708,7 @@ Adaptive thinking is particularly well suited to the following workload patterns When using adaptive thinking, evaluate `medium` and `high` effort on your tasks. The right level depends on your workload's tradeoff between quality, latency, and token usage. -```python nocheck +```python Python nocheck client.messages.create( model="claude-sonnet-4-6", max_tokens=64000, @@ -720,7 +724,7 @@ If you need to keep `budget_tokens` temporarily while migrating, a budget around **For coding use cases** (agentic coding, tool-heavy workflows, code generation), start with `medium` effort: -```python nocheck +```python Python nocheck client.messages.create( model="claude-sonnet-4-6", max_tokens=16384, @@ -732,7 +736,7 @@ client.messages.create( **For chat and non-coding use cases** (chat, content generation, search, classification), start with `low` effort: -```python nocheck +```python Python nocheck client.messages.create( model="claude-sonnet-4-6", max_tokens=8192, diff --git a/content/en/build-with-claude/search-results.md b/content/en/build-with-claude/search-results.md index 1ef11dafd..1c94eca34 100644 --- a/content/en/build-with-claude/search-results.md +++ b/content/en/build-with-claude/search-results.md @@ -839,6 +839,42 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +messages: + - role: user + content: + - type: search_result + source: https://docs.company.com/api-reference + title: API Reference - Authentication + content: + - type: text + text: >- + All API requests must include an API key in the Authorization + header. Keys can be generated from the dashboard. Rate limits: + 1000 requests per hour for standard tier, 10000 for premium. + citations: + enabled: true + - type: search_result + source: https://docs.company.com/quickstart + title: Getting Started Guide + content: + - type: text + text: >- + To get started: 1) Sign up for an account, 2) Generate an API + key from the dashboard, 3) Install our SDK using pip install + company-sdk, 4) Initialize the client with your API key. + citations: + enabled: true + - type: text + text: >- + Based on these search results, how do I authenticate API requests + and what are the rate limits? +YAML +``` + ```python Python hidelines={1} from anthropic import Anthropic from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam diff --git a/content/en/build-with-claude/skills-guide.md b/content/en/build-with-claude/skills-guide.md index 15d60c1e7..b0b92fdb4 100644 --- a/content/en/build-with-claude/skills-guide.md +++ b/content/en/build-with-claude/skills-guide.md @@ -110,6 +110,26 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant beta:messages create \ + --beta code-execution-2025-08-25 \ + --beta skills-2025-10-02 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +container: + skills: + - type: anthropic + skill_id: pptx + version: latest +messages: + - role: user + content: Create a presentation about renewable energy +tools: + - type: code_execution_20250825 + name: code_execution +YAML +``` + ```python Python nocheck hidelines={1..2} import anthropic @@ -416,6 +436,47 @@ curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \ echo "Downloaded: $FILENAME" ``` + + + +```bash CLI hidelines={1} +cd "$(mktemp -d)" +# Step 1: Use the xlsx Skill to create a file +# Step 2: Extract file_id from the response via --transform (GJSON path) +FILE_ID=$(ant beta:messages create \ + --beta code-execution-2025-08-25 \ + --beta skills-2025-10-02 \ + --transform 'content.#.content.content.#.file_id|@flatten|0' \ + --format yaml <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +container: + skills: + - type: anthropic + skill_id: xlsx + version: latest +messages: + - role: user + content: Create an Excel file with a simple budget spreadsheet +tools: + - type: code_execution_20250825 + name: code_execution +YAML +) + +# Step 3: Get the filename from file metadata +FILENAME=$(ant beta:files retrieve-metadata \ + --file-id "$FILE_ID" \ + --transform filename --format yaml) + +# Step 4: Download the file using Files API +ant beta:files download \ + --file-id "$FILE_ID" \ + --output "$FILENAME" > /dev/null + +printf 'Downloaded: %s\n' "$FILENAME" +``` + @@ -960,6 +1021,24 @@ curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \ -H "anthropic-beta: files-api-2025-04-14" ``` +```bash CLI +# Get file metadata +ant beta:files retrieve-metadata --file-id "$FILE_ID" \ + --transform '{filename,size_bytes}' --format yaml \ + | { read -r _ name; read -r _ size + printf 'Filename: %s, Size: %s bytes\n' "$name" "$size"; } + +# List all files +ant beta:files list \ + --transform '{filename,created_at}' --format yaml \ + | while read -r _ name && read -r _ date; do + printf '%s - %s\n' "$name" "${date//\"/}" + done + +# Delete a file +ant beta:files delete --file-id "$FILE_ID" >/dev/null +``` + ```python Python nocheck hidelines={1..2} import anthropic @@ -1172,6 +1251,45 @@ For complete details on the Files API, see the [Files API documentation](/docs/e Reuse the same container across multiple messages by specifying the container ID: +```bash CLI +# First request creates container +CONTAINER_ID=$(ant beta:messages create \ + --beta code-execution-2025-08-25 --beta skills-2025-10-02 \ + --transform container.id --format yaml <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +container: + skills: + - {type: anthropic, skill_id: xlsx, version: latest} +messages: + - role: user + content: Analyze this sales data +tools: + - {type: code_execution_20250825, name: code_execution} +YAML +) + +# Continue conversation with same container +ant beta:messages create \ + --beta code-execution-2025-08-25 --beta skills-2025-10-02 < "$RESP" <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +container: + skills: + - type: custom + skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv + version: latest +messages: + - role: user + content: Process this large dataset +tools: + - type: code_execution_20250825 + name: code_execution +YAML + +# Handle pause_turn for long operations (up to 10 iterations) +for _ in {1..10}; do + [[ $(jq -r '.stop_reason' "$RESP") == pause_turn ]] || break + + CONTAINER_ID=$(jq -r '.container.id' "$RESP") + + # Continue in the same container, appending the prior response's + # content array to messages as the assistant turn. + ant beta:messages create \ + --beta code-execution-2025-08-25 \ + --beta skills-2025-10-02 \ + > "$RESP" < + ```bash Shell nocheck curl -X POST "https://api.anthropic.com/v1/skills" \ @@ -2402,6 +2598,21 @@ curl -X POST "https://api.anthropic.com/v1/skills" \ -F "files[]=@financial_skill/analyze.py;filename=financial_skill/analyze.py" ``` +```bash CLI nocheck +# Option 1: Upload individual files (one --file flag per file) +ant beta:skills create \ + --display-title "Financial Analysis" \ + --file financial_skill/SKILL.md \ + --file financial_skill/analyze.py \ + --beta skills-2025-10-02 + +# Option 2: Upload a zip archive +ant beta:skills create \ + --display-title "Financial Analysis" \ + --file financial_analysis_skill.zip \ + --beta skills-2025-10-02 +``` + ```python Python nocheck hidelines={1..2} import anthropic @@ -2693,7 +2904,7 @@ For complete request/response schemas, see the [Create Skill API reference](/doc Retrieve all Skills available to your workspace, including both Anthropic pre-built Skills and your custom Skills. Use the `source` parameter to filter by skill type: - + ```bash Shell # List all Skills curl "https://api.anthropic.com/v1/skills" \ @@ -2708,6 +2919,14 @@ curl "https://api.anthropic.com/v1/skills?source=custom" \ -H "anthropic-beta: skills-2025-10-02" ``` +```bash CLI +# List all Skills +ant beta:skills list + +# List only custom Skills +ant beta:skills list --source custom +``` + ```python Python # List all Skills skills = client.beta.skills.list(betas=["skills-2025-10-02"]) @@ -2891,7 +3110,7 @@ See the [List Skills API reference](/docs/en/api/skills/list-skills) for paginat Get details about a specific Skill: - + ```bash Shell nocheck curl "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \ @@ -2900,6 +3119,11 @@ curl "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \ -H "anthropic-beta: skills-2025-10-02" ``` +```bash CLI nocheck +ant beta:skills retrieve \ + --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv +``` + ```python Python nocheck skill = client.beta.skills.retrieve( skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"] @@ -3036,7 +3260,7 @@ puts "Created: #{skill.created_at}" To delete a Skill, you must first delete all its versions: - + ```bash Shell nocheck # Delete all versions first, then delete the Skill @@ -3046,6 +3270,23 @@ curl -X DELETE "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrSt -H "anthropic-beta: skills-2025-10-02" ``` +```bash CLI nocheck +# Step 1: Delete all versions +ant beta:skills:versions list \ + --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \ + --transform version --format yaml \ + | tr -d '"' \ + | while read -r VERSION; do + ant beta:skills:versions delete \ + --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \ + --version "$VERSION" >/dev/null + done + +# Step 2: Delete the Skill +ant beta:skills delete \ + --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null +``` + ```python Python nocheck # Step 1: Delete all versions versions = client.beta.skills.versions.list( @@ -3285,7 +3526,7 @@ Skills support versioning to manage updates safely: - Use `"latest"` to always get the most recent version - Create new versions when updating Skill files - + ```bash Shell nocheck # Create a new version @@ -3338,6 +3579,52 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI nocheck +# Create a new version +VERSION_NUMBER=$(ant beta:skills:versions create \ + --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \ + --file updated_skill/SKILL.md \ + --transform version --format yaml) + +# Use specific version +ant beta:messages create \ + --beta code-execution-2025-08-25 \ + --beta skills-2025-10-02 < +```bash CLI nocheck +if ! RESULT=$(ant beta:messages create \ + --beta code-execution-2025-08-25 \ + --beta skills-2025-10-02 \ + --transform-error error.message --format-error yaml 2>&1 <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +container: + skills: + - type: custom + skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv + version: latest +messages: + - role: user + content: Process data +tools: + - type: code_execution_20250825 + name: code_execution +YAML +); then + case "$RESULT" in + *skill*) + printf 'Skill error: %s\n' "$RESULT" + # Handle skill-specific errors + ;; + *) + printf '%s\n' "$RESULT" >&2 + exit 1 + ;; + esac +fi +``` + ```python Python nocheck hidelines={1..2} import anthropic diff --git a/content/en/build-with-claude/streaming.md b/content/en/build-with-claude/streaming.md index f613f4f61..1a9a35900 100644 --- a/content/en/build-with-claude/streaming.md +++ b/content/en/build-with-claude/streaming.md @@ -9,6 +9,18 @@ When creating a Message, you can set `"stream": true` to incrementally stream th The [Python](https://github.com/anthropics/anthropic-sdk-python) and [TypeScript](https://github.com/anthropics/anthropic-sdk-typescript) SDKs offer multiple ways of streaming. The [PHP](https://github.com/anthropics/anthropic-sdk-php) SDK provides streaming via `createStream()`. The Python SDK allows both sync and async streams. See the documentation in each SDK for details. + ```bash CLI + ant messages create --stream --format jsonl \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --message '{role: user, content: "Hello"}' \ + | while IFS= read -r event; do + [[ $event == *'"text_delta"'* ]] || continue + text=${event#*'"text":"'} + printf '%b' "${text%\"*}" + done + ``` + ```python Python hidelines={1..2} import anthropic @@ -170,6 +182,19 @@ The [Python](https://github.com/anthropics/anthropic-sdk-python) and [TypeScript If you don't need to process text as it arrives, the SDKs provide a way to use streaming under the hood while returning the complete `Message` object, identical to what `.create()` returns. This is especially useful for requests with large `max_tokens` values, where the SDKs require streaming to avoid HTTP timeouts. + ```bash CLI + # The ant CLI's --stream flag emits one event per line and does not + # accumulate into a final Message. For long generations, stream the + # raw events: + ant messages create --stream --format jsonl <<'YAML' + model: claude-opus-4-6 + max_tokens: 128000 + messages: + - role: user + content: Write a detailed analysis... + YAML + ``` + ```python Python hidelines={1..2} import anthropic @@ -451,6 +476,13 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create --stream --format jsonl \ + --model claude-opus-4-6 \ + --max-tokens 256 \ + --message '{role: user, content: Hello}' +``` + ```python Python hidelines={1..2} import anthropic @@ -683,6 +715,29 @@ This request asks Claude to use a tool to report the weather. }' ``` +```bash CLI +ant messages create --stream --format jsonl <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +tools: + - name: get_weather + description: Get the current weather in a given location + input_schema: + type: object + properties: + location: + type: string + description: The city and state, e.g. San Francisco, CA + required: + - location +tool_choice: + type: any +messages: + - role: user + content: What is the weather like in San Francisco? +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -1102,6 +1157,14 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create --stream --format jsonl \ + --model claude-opus-4-6 \ + --max-tokens 20000 \ + --thinking '{type: enabled, budget_tokens: 16000}' \ + --message '{role: user, content: What is the greatest common divisor of 1071 and 462?}' +``` + ```python Python hidelines={1..2} import anthropic @@ -1367,6 +1430,14 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create --stream --format jsonl \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --tool '{type: web_search_20250305, name: web_search, max_uses: 5}' \ + --message '{role: user, content: What is the weather like in New York City today?}' +``` + ```python Python hidelines={1..2} import anthropic diff --git a/content/en/build-with-claude/structured-outputs.md b/content/en/build-with-claude/structured-outputs.md index 68109bf6d..451d95339 100644 --- a/content/en/build-with-claude/structured-outputs.md +++ b/content/en/build-with-claude/structured-outputs.md @@ -82,6 +82,33 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create \ + --transform 'content.0.text|@fromstr' \ + --format jsonl <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +messages: + - role: user + content: >- + Extract the key information from this email: John Smith + (john@example.com) is interested in our Enterprise plan and wants + to schedule a demo for next Tuesday at 2pm. +output_config: + format: + type: json_schema + schema: + type: object + properties: + name: {type: string} + email: {type: string} + plan_interest: {type: string} + demo_requested: {type: boolean} + required: [name, email, plan_interest, demo_requested] + additionalProperties: false +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -348,7 +375,7 @@ puts response.content[0].text **Response format:** Valid JSON matching your schema in `response.content[0].text` -```json +```json Output { "name": "John Smith", "email": "john@example.com", @@ -387,10 +414,39 @@ Instead of writing raw JSON schemas, you can use familiar schema definition tool - **TypeScript**: [Zod](https://zod.dev/) schemas with `zodOutputFormat()` - **Java**: Plain Java classes with automatic schema derivation via `outputConfig(Class)` - **Ruby**: `Anthropic::BaseModel` classes with `output_config: {format: Model}` -- **C#**, **Go**, **PHP**: Raw JSON schemas passed via `output_config` +- **CLI**, **C#**, **Go**, **PHP**: Raw JSON schemas passed via `output_config` +```bash CLI +{ read -r _ NAME; read -r _ EMAIL; } < <( + ant messages create \ + --transform 'content.0.text|@fromstr|{name,email}' --format yaml <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +messages: + - role: user + content: >- + Extract the key information from this email: John Smith + (john@example.com) is interested in our Enterprise plan and wants + to schedule a demo for next Tuesday at 2pm. +output_config: + format: + type: json_schema + schema: + type: object + properties: + name: {type: string} + email: {type: string} + plan_interest: {type: string} + demo_requested: {type: boolean} + required: [name, email, plan_interest, demo_requested] + additionalProperties: false +YAML +) +printf '%s (%s)\n' "$NAME" "$EMAIL" +``` + ```python Python from pydantic import BaseModel from anthropic import Anthropic @@ -650,6 +706,47 @@ puts "#{contact.name} (#{contact.email})" Each SDK provides helpers that make working with structured outputs easier. See individual SDK pages for full details. + + +**Raw JSON schemas via heredoc body** + +The CLI passes raw JSON schemas as a YAML heredoc body. Use the GJSON `@fromstr` modifier with `--transform` to parse the JSON string returned in `content[0].text` and project specific fields. + +
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    + +```bash +ant messages create \ + --transform 'content.0.text|@fromstr|{name,email}' \ + --format yaml <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +messages: + - role: user + content: >- + Extract contact info: John Smith, john@example.com, + interested in the Pro plan +output_config: + format: + type: json_schema + schema: + type: object + properties: + name: {type: string} + email: {type: string} + plan_interest: {type: string} + required: [name, email, plan_interest] + additionalProperties: false +YAML +``` + +```yaml Output +name: John Smith +email: john@example.com +``` + +
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    + +
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    **`client.messages.parse()` (Recommended)** @@ -1214,6 +1311,32 @@ Extract structured data from unstructured text: +```bash CLI +ant messages create \ + --transform 'content.0.text|@fromstr' --format jsonl <<'YAML' +model: claude-opus-4-6 +max_tokens: 4096 +messages: + - role: user + content: "Extract invoice data from: Invoice #12345, Date: 2024-01-15, Total: $500.00" +output_config: + format: + type: json_schema + schema: + type: object + properties: + invoice_number: {type: string} + date: {type: string} + total_amount: {type: number} + line_items: + type: array + items: {type: object, additionalProperties: false} + customer_name: {type: string} + required: [invoice_number, date, total_amount, line_items, customer_name] + additionalProperties: false +YAML +``` + ```python Python nocheck from pydantic import BaseModel from typing import List @@ -1543,6 +1666,39 @@ Classify content with structured categories: +```bash CLI +ant messages create \ + --transform 'content.0.text|@fromstr' --format jsonl <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +messages: + - role: user + content: "Classify this feedback: Great product, fast shipping!" +output_config: + format: + type: json_schema + schema: + type: object + properties: + category: + type: string + confidence: + type: number + tags: + type: array + items: + type: string + sentiment: + type: string + required: + - category + - confidence + - tags + - sentiment + additionalProperties: false +YAML +``` + ```python Python hidelines={1} from anthropic import Anthropic from pydantic import BaseModel @@ -1799,6 +1955,41 @@ Generate API-ready responses: +```bash CLI +ant messages create \ + --transform 'content.0.text' --format yaml <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +output_config: + format: + type: json_schema + schema: + type: object + properties: + status: + type: string + data: + type: object + additionalProperties: false + errors: + type: array + items: + type: object + additionalProperties: false + metadata: + type: object + additionalProperties: false + required: + - status + - data + - metadata + additionalProperties: false +messages: + - role: user + content: "Process this request: ..." +YAML +``` + ```python Python hidelines={1} from anthropic import Anthropic from pydantic import BaseModel @@ -2104,6 +2295,45 @@ When combined, Claude can call tools with guaranteed-valid parameters AND return +```bash CLI +ant messages create <<'YAML' +model: claude-opus-4-6 +max_tokens: 1024 +messages: + - role: user + content: Help me plan a trip to Paris departing May 15, 2026 +# JSON outputs: structured response format +output_config: + format: + type: json_schema + schema: + type: object + properties: + summary: + type: string + next_steps: + type: array + items: + type: string + required: [summary, next_steps] + additionalProperties: false +# Strict tool use: guaranteed tool parameters +tools: + - name: search_flights + strict: true + input_schema: + type: object + properties: + destination: + type: string + date: + type: string + format: date + required: [destination, date] + additionalProperties: false +YAML +``` + ```python Python response = client.messages.create( model="claude-opus-4-6", diff --git a/content/en/build-with-claude/token-counting.md b/content/en/build-with-claude/token-counting.md index 7aade1a3c..b136d08ec 100644 --- a/content/en/build-with-claude/token-counting.md +++ b/content/en/build-with-claude/token-counting.md @@ -45,6 +45,13 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ }' ``` +```bash CLI +ant messages count-tokens \ + --model claude-opus-4-6 \ + --system "You are a scientist" \ + --message '{role: user, content: "Hello, Claude"}' +``` + ```python Python hidelines={1..2} import anthropic @@ -193,7 +200,7 @@ puts response ``` -```json JSON +```json Output { "input_tokens": 14 } ``` @@ -237,6 +244,26 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ }' ``` +```bash CLI +ant messages count-tokens <<'YAML' +model: claude-opus-4-6 +tools: + - name: get_weather + description: Get the current weather in a given location + input_schema: + type: object + properties: + location: + type: string + description: The city and state, e.g. San Francisco, CA + required: + - location +messages: + - role: user + content: What's the weather like in San Francisco? +YAML +``` + ```python Python hidelines={1..2} import anthropic @@ -499,7 +526,7 @@ puts response ``` -```json JSON +```json Output { "input_tokens": 403 } ``` @@ -534,6 +561,25 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ EOF ``` +```bash CLI nocheck +IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" +curl -s "$IMAGE_URL" -o ./ant.jpg + +ant messages count-tokens <<'YAML' +model: claude-opus-4-6 +messages: + - role: user + content: + - type: image + source: + type: base64 + media_type: image/jpeg + data: "@./ant.jpg" + - type: text + text: Describe this image +YAML +``` + ```python Python nocheck hidelines={1} import anthropic import base64 @@ -834,7 +880,7 @@ puts response ``` -```json JSON +```json Output { "input_tokens": 1551 } ``` @@ -886,6 +932,29 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ }' ``` +```bash CLI nocheck +ant messages count-tokens <<'YAML' +model: claude-sonnet-4-6 +thinking: + type: enabled + budget_tokens: 16000 +messages: + - role: user + content: Are there an infinite number of prime numbers such that n mod 4 == 3? + - role: assistant + content: + - type: thinking + thinking: >- + This is a nice number theory question. Lets think about it step by step... + signature: >- + EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV... + - type: text + text: Yes, there are infinitely many prime numbers p such that p mod 4 = 3... + - role: user + content: Can you write a formal proof? +YAML +``` + ```python Python nocheck hidelines={1..2} import anthropic @@ -1187,7 +1256,7 @@ puts response ``` -```json JSON +```json Output { "input_tokens": 88 } ``` @@ -1230,6 +1299,25 @@ curl https://api.anthropic.com/v1/messages/count_tokens \ EOF ``` +```bash CLI hidelines={1..3} +PDF_URL="https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf" +curl -s "$PDF_URL" -o document.pdf + +ant messages count-tokens <<'YAML' +model: claude-opus-4-6 +messages: + - role: user + content: + - type: document + source: + type: base64 + media_type: application/pdf + data: "@./document.pdf" + - type: text + text: Please summarize this document. +YAML +``` + ```python Python nocheck import base64 import anthropic @@ -1502,7 +1590,7 @@ puts response ```
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    -```json JSON +```json Output { "input_tokens": 2188 } ``` diff --git a/content/en/build-with-claude/vision.md b/content/en/build-with-claude/vision.md index 8128f2683..931699def 100644 --- a/content/en/build-with-claude/vision.md +++ b/content/en/build-with-claude/vision.md @@ -307,6 +307,25 @@ Below are examples of how to include images in a Messages API request using base } EOF ``` + ```bash CLI + curl -sSo ./image.jpg \ + https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg + + ant messages create <<'YAML' + model: claude-opus-4-6 + max_tokens: 1024 + messages: + - role: user + content: + - type: image + source: + type: base64 + media_type: image/jpeg + data: "@./image.jpg" + - type: text + text: Describe this image. + YAML + ``` ```python Python hidelines={1..2} import anthropic @@ -578,6 +597,21 @@ Below are examples of how to include images in a Messages API request using base ] }' ``` + ```bash CLI + ant messages create <<'YAML' + model: claude-opus-4-6 + max_tokens: 1024 + messages: + - role: user + content: + - type: image + source: + type: url + url: https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg + - type: text + text: Describe this image. + YAML + ``` ```python Python hidelines={1..2} import anthropic @@ -855,6 +889,34 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI hidelines={1} +cd "$(mktemp -d)" +curl -sSo image.jpg \ + https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg + +# First, upload your image to the Files API +FILE_ID=$(ant beta:files upload \ + --file ./image.jpg \ + --transform id --format yaml) + +# Then use the returned file_id in your message +ant beta:messages create \ + --beta files-api-2025-04-14 \ + --transform content --format yaml < -See [Messages API examples](/docs/en/api/messages) for more example code and parameter details. +See [Messages API examples](/docs/en/api/messages/create) for more example code and parameter details.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    @@ -1392,7 +1454,7 @@ Ask Claude to contrast two images, then ask a follow-up question comparing the f | User | Image 1: \[Image 3\] Image 2: \[Image 4\] Are these images similar to the first two? | | Assistant | \[Claude's response\] | -When using the API, simply insert new images into the array of Messages in the `user` role as part of any standard [multiturn conversation](/docs/en/api/messages) structure. +When using the API, simply insert new images into the array of Messages in the `user` role as part of any standard [multiturn conversation](/docs/en/api/messages/create) structure.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    @@ -1520,6 +1582,6 @@ Always carefully review and verify Claude's image interpretations, especially fo Ready to start building with images using Claude? Here are a few helpful resources: - [Multimodal cookbook](https://platform.claude.com/cookbook/multimodal-getting-started-with-vision): This cookbook has tips on [getting started with images](https://platform.claude.com/cookbook/multimodal-getting-started-with-vision) and [best practice techniques](https://platform.claude.com/cookbook/multimodal-best-practices-for-vision) to ensure the highest quality performance with images. See how you can effectively prompt Claude with images to carry out tasks such as [interpreting and analyzing charts](https://platform.claude.com/cookbook/multimodal-reading-charts-graphs-powerpoints) or [extracting content from forms](https://platform.claude.com/cookbook/multimodal-how-to-transcribe-text). -- [API reference](/docs/en/api/messages): Documentation for the Messages API, including example [API calls involving images](/docs/en/build-with-claude/working-with-messages#vision). +- [API reference](/docs/en/api/messages/create): Documentation for the Messages API, including example [API calls involving images](/docs/en/build-with-claude/working-with-messages#vision). If you have any other questions, reach out to the [support team](https://support.claude.com/). You can also join the [developer community](https://www.anthropic.com/discord) to connect with other creators and get help from Anthropic experts. \ No newline at end of file diff --git a/content/en/build-with-claude/working-with-messages.md b/content/en/build-with-claude/working-with-messages.md index 74cef07b3..0cf071271 100644 --- a/content/en/build-with-claude/working-with-messages.md +++ b/content/en/build-with-claude/working-with-messages.md @@ -4,7 +4,15 @@ Practical patterns and examples for using the Messages API effectively --- -This guide covers common patterns for working with the Messages API, including basic requests, multi-turn conversations, prefill techniques, and vision capabilities. For complete API specifications, see the [Messages API reference](/docs/en/api/messages). +Anthropic offers two ways to build with Claude, each suited to different use cases: + +| | Messages API | Claude Managed Agents | +|---|---|---| +| **What it is** | Direct model prompting access | Pre-built, configurable agent harness that runs in managed infrastructure | +| **Best for** | Custom agent loops and fine-grained control | Long-running tasks and asynchronous work | +| **Learn more** | [Messages API docs](/docs/en/build-with-claude/working-with-messages) | [Claude Managed Agents docs](/docs/en/managed-agents/overview) | + +This guide covers common patterns for working with the Messages API, including basic requests, multi-turn conversations, prefill techniques, and vision capabilities. For complete API specifications, see the [Messages API reference](/docs/en/api/messages/create). This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned. @@ -29,6 +37,13 @@ This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-cla }' ``` + ```bash CLI + ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --message '{role: user, content: "Hello, Claude"}' + ``` + ```python Python hidelines={1..2} import anthropic @@ -159,7 +174,7 @@ This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-cla ```
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    -```json JSON +```json Output { "id": "msg_01XFDUDYJgAACzvnptvVoYEL", "type": "message", @@ -204,6 +219,15 @@ curl https://api.anthropic.com/v1/messages \ }' ``` +```bash CLI +ant messages create \ + --model claude-opus-4-6 \ + --max-tokens 1024 \ + --message '{role: user, content: "Hello, Claude"}' \ + --message '{role: assistant, content: "Hello!"}' \ + --message '{role: user, content: "Can you describe LLMs to me?"}' +``` + ```python Python hidelines={1..2} import anthropic @@ -358,7 +382,7 @@ puts message ```
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    -```json JSON +```json Output { "id": "msg_018gCsTGsXkYJVqYPxTgDHBU", "type": "message", @@ -400,6 +424,18 @@ You can pre-fill part of Claude's response in the last position of the input mes }' ``` + ```bash CLI + ant messages create <<'YAML' + model: claude-sonnet-4-5 + max_tokens: 1 + messages: + - role: user + content: "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae" + - role: assistant + content: "The answer is (" + YAML + ``` + ```python Python hidelines={1..2} import anthropic @@ -555,7 +591,7 @@ You can pre-fill part of Claude's response in the last position of the input mes ```
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    -```json JSON +```json Output { "id": "msg_01Q8Faay6S7QPTvEUUQARt7h", "type": "message", @@ -635,6 +671,44 @@ Claude can read both text and images in requests. Images can be supplied using t ``` + ```bash CLI nocheck + IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" + + # Option 1: Base64-encoded image (CLI auto-encodes binary @file refs) + curl -s "$IMAGE_URL" -o ./ant.jpg + + ant messages create <<'YAML' + model: claude-opus-4-6 + max_tokens: 1024 + messages: + - role: user + content: + - type: image + source: + type: base64 + media_type: image/jpeg + data: "@./ant.jpg" + - type: text + text: What is in the above image? + YAML + + # Option 2: URL-referenced image + ant messages create < -```json JSON +```json Output { "id": "msg_01EcyWo6m4hyW8KHs2y2pei5", "type": "message", diff --git a/content/en/build-with-claude/workspaces.md b/content/en/build-with-claude/workspaces.md index acaf1c42a..a6df39616 100644 --- a/content/en/build-with-claude/workspaces.md +++ b/content/en/build-with-claude/workspaces.md @@ -23,6 +23,7 @@ Members can have different roles in each workspace, allowing fine-grained access | Role | Permissions | |------|-------------| | Workspace User | Use the Workbench only | +| Workspace Limited Developer | Create and manage API keys, use the API. Cannot access session tracing views or download files. | | Workspace Developer | Create and manage API keys, use the API | | Workspace Admin | Full control over workspace settings and members | | Workspace Billing | View workspace billing information (inherited from organization billing role) | @@ -287,7 +288,7 @@ Organization admins automatically get the Workspace Admin role in all workspaces
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    -Organization users and developers can be assigned Workspace Admin, Workspace Developer, or Workspace User roles. The Workspace Billing role cannot be manually assigned; it's inherited from having the organization `billing` role. +Organization users and developers can be assigned Workspace Admin, Workspace Developer, Workspace Limited Developer, or Workspace User roles. The Workspace Billing role cannot be manually assigned; it's inherited from having the organization `billing` role.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    diff --git a/content/en/docs/claude-code/agent-sdk/agent-loop.md b/content/en/docs/claude-code/agent-sdk/agent-loop.md new file mode 100644 index 000000000..b7cfa454f --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/agent-loop.md @@ -0,0 +1,394 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# How the agent loop works + +> Understand the message lifecycle, tool execution, context window, and architecture that power your SDK agents. + +The Agent SDK lets you embed Claude Code's autonomous agent loop in your own applications. The SDK is a standalone package that gives you programmatic control over tools, permissions, cost limits, and output. You don't need the Claude Code CLI installed to use it. + +When you start an agent, the SDK runs the same [execution loop that powers Claude Code](/en/how-claude-code-works#the-agentic-loop): Claude evaluates your prompt, calls tools to take action, receives the results, and repeats until the task is complete. This page explains what happens inside that loop so you can build, debug, and optimize your agents effectively. + +## The loop at a glance + +Every agent session follows the same cycle: + +Agent loop: prompt enters, Claude evaluates, branches to tool calls or final answer + +1. **Receive prompt.** Claude receives your prompt, along with the system prompt, tool definitions, and conversation history. The SDK yields a [`SystemMessage`](#message-types) with subtype `"init"` containing session metadata. +2. **Evaluate and respond.** Claude evaluates the current state and determines how to proceed. It may respond with text, request one or more tool calls, or both. The SDK yields an [`AssistantMessage`](#message-types) containing the text and any tool call requests. +3. **Execute tools.** The SDK runs each requested tool and collects the results. Each set of tool results feeds back to Claude for the next decision. You can use [hooks](/en/agent-sdk/hooks) to intercept, modify, or block tool calls before they run. +4. **Repeat.** Steps 2 and 3 repeat as a cycle. Each full cycle is one turn. Claude continues calling tools and processing results until it produces a response with no tool calls. +5. **Return result.** The SDK yields a final [`AssistantMessage`](#message-types) with the text response (no tool calls), followed by a [`ResultMessage`](#message-types) with the final text, token usage, cost, and session ID. + +A quick question ("what files are here?") might take one or two turns of calling `Glob` and responding with the results. A complex task ("refactor the auth module and update the tests") can chain dozens of tool calls across many turns, reading files, editing code, and running tests, with Claude adjusting its approach based on each result. + +## Turns and messages + +A turn is one round trip inside the loop: Claude produces output that includes tool calls, the SDK executes those tools, and the results feed back to Claude automatically. This happens without yielding control back to your code. Turns continue until Claude produces output with no tool calls, at which point the loop ends and the final result is delivered. + +Consider what a full session might look like for the prompt "Fix the failing tests in auth.ts". + +First, the SDK sends your prompt to Claude and yields a [`SystemMessage`](#message-types) with the session metadata. Then the loop begins: + +1. **Turn 1:** Claude calls `Bash` to run `npm test`. The SDK yields an [`AssistantMessage`](#message-types) with the tool call, executes the command, then yields a [`UserMessage`](#message-types) with the output (three failures). +2. **Turn 2:** Claude calls `Read` on `auth.ts` and `auth.test.ts`. The SDK returns the file contents and yields an `AssistantMessage`. +3. **Turn 3:** Claude calls `Edit` to fix `auth.ts`, then calls `Bash` to re-run `npm test`. All three tests pass. The SDK yields an `AssistantMessage`. +4. **Final turn:** Claude produces a text-only response with no tool calls: "Fixed the auth bug, all three tests pass now." The SDK yields a final `AssistantMessage` with this text, then a [`ResultMessage`](#message-types) with the same text plus cost and usage. + +That was four turns: three with tool calls, one final text-only response. + +You can cap the loop with `max_turns` / `maxTurns`, which counts tool-use turns only. For example, `max_turns=2` in the loop above would have stopped before the edit step. You can also use `max_budget_usd` / `maxBudgetUsd` to cap turns based on a spend threshold. + +Without limits, the loop runs until Claude finishes on its own, which is fine for well-scoped tasks but can run long on open-ended prompts ("improve this codebase"). Setting a budget is a good default for production agents. See [Turns and budget](#turns-and-budget) below for the option reference. + +## Message types + +As the loop runs, the SDK yields a stream of messages. Each message carries a type that tells you what stage of the loop it came from. The five core types are: + +* **`SystemMessage`:** session lifecycle events. The `subtype` field distinguishes them: `"init"` is the first message (session metadata), and `"compact_boundary"` fires after [compaction](#automatic-compaction). In TypeScript, the compact boundary is its own [`SDKCompactBoundaryMessage`](/en/agent-sdk/typescript#sdk-compact-boundary-message) type rather than a subtype of `SDKSystemMessage`. +* **`AssistantMessage`:** emitted after each Claude response, including the final text-only one. Contains text content blocks and tool call blocks from that turn. +* **`UserMessage`:** emitted after each tool execution with the tool result content sent back to Claude. Also emitted for any user inputs you stream mid-loop. +* **`StreamEvent`:** only emitted when partial messages are enabled. Contains raw API streaming events (text deltas, tool input chunks). See [Stream responses](/en/agent-sdk/streaming-output). +* **`ResultMessage`:** the last message, always. Contains the final text result, token usage, cost, and session ID. Check the `subtype` field to determine whether the task succeeded or hit a limit. See [Handle the result](#handle-the-result). + +These five types cover the full agent loop lifecycle in both SDKs. The TypeScript SDK also yields additional observability events (hook events, tool progress, rate limits, task notifications) that provide extra detail but are not required to drive the loop. See the [Python message types reference](/en/agent-sdk/python#message-types) and [TypeScript message types reference](/en/agent-sdk/typescript#message-types) for the complete lists. + +### Handle messages + +Which messages you handle depends on what you're building: + +* **Final results only:** handle `ResultMessage` to get the output, cost, and whether the task succeeded or hit a limit. +* **Progress updates:** handle `AssistantMessage` to see what Claude is doing each turn, including which tools it called. +* **Live streaming:** enable partial messages (`include_partial_messages` in Python, `includePartialMessages` in TypeScript) to get `StreamEvent` messages in real time. See [Stream responses in real-time](/en/agent-sdk/streaming-output). + +How you check message types depends on the SDK: + +* **Python:** check message types with `isinstance()` against classes imported from `claude_agent_sdk` (for example, `isinstance(message, ResultMessage)`). +* **TypeScript:** check the `type` string field (for example, `message.type === "result"`). `AssistantMessage` and `UserMessage` wrap the raw API message in a `.message` field, so content blocks are at `message.message.content`, not `message.content`. + + + + ```python Python theme={null} + from claude_agent_sdk import query, AssistantMessage, ResultMessage + + async for message in query(prompt="Summarize this project"): + if isinstance(message, AssistantMessage): + print(f"Turn completed: {len(message.content)} content blocks") + if isinstance(message, ResultMessage): + if message.subtype == "success": + print(message.result) + else: + print(f"Stopped: {message.subtype}") + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ prompt: "Summarize this project" })) { + if (message.type === "assistant") { + console.log(`Turn completed: ${message.message.content.length} content blocks`); + } + if (message.type === "result") { + if (message.subtype === "success") { + console.log(message.result); + } else { + console.log(`Stopped: ${message.subtype}`); + } + } + } + ``` + + + +## Tool execution + +Tools give your agent the ability to take action. Without tools, Claude can only respond with text. With tools, Claude can read files, run commands, search code, and interact with external services. + +### Built-in tools + +The SDK includes the same tools that power Claude Code: + +| Category | Tools | What they do | +| :------------------ | :----------------------------------------------- | :-------------------------------------------------------------------------- | +| **File operations** | `Read`, `Edit`, `Write` | Read, modify, and create files | +| **Search** | `Glob`, `Grep` | Find files by pattern, search content with regex | +| **Execution** | `Bash` | Run shell commands, scripts, git operations | +| **Web** | `WebSearch`, `WebFetch` | Search the web, fetch and parse pages | +| **Discovery** | `ToolSearch` | Dynamically find and load tools on-demand instead of preloading all of them | +| **Orchestration** | `Agent`, `Skill`, `AskUserQuestion`, `TodoWrite` | Spawn subagents, invoke skills, ask the user, track tasks | + +Beyond built-in tools, you can: + +* **Connect external services** with [MCP servers](/en/agent-sdk/mcp) (databases, browsers, APIs) +* **Define custom tools** with [custom tool handlers](/en/agent-sdk/custom-tools) +* **Load project skills** via [setting sources](/en/agent-sdk/claude-code-features) for reusable workflows + +### Tool permissions + +Claude determines which tools to call based on the task, but you control whether those calls are allowed to execute. You can auto-approve specific tools, block others entirely, or require approval for everything. Three options work together to determine what runs: + +* **`allowed_tools` / `allowedTools`** auto-approves listed tools. A read-only agent with `["Read", "Glob", "Grep"]` in its allowed tools list runs those tools without prompting. Tools not listed are still available but require permission. +* **`disallowed_tools` / `disallowedTools`** blocks listed tools, regardless of other settings. See [Permissions](/en/agent-sdk/permissions) for the order that rules are checked before a tool runs. +* **`permission_mode` / `permissionMode`** controls what happens to tools that aren't covered by allow or deny rules. See [Permission mode](#permission-mode) for available modes. + +You can also scope individual tools with rules like `"Bash(npm:*)"` to allow only specific commands. See [Permissions](/en/agent-sdk/permissions) for the full rule syntax. + +When a tool is denied, Claude receives a rejection message as the tool result and typically attempts a different approach or reports that it couldn't proceed. + +### Parallel tool execution + +When Claude requests multiple tool calls in a single turn, both SDKs can run them concurrently or sequentially depending on the tool. Read-only tools (like `Read`, `Glob`, `Grep`, and MCP tools marked as read-only) can run concurrently. Tools that modify state (like `Edit`, `Write`, and `Bash`) run sequentially to avoid conflicts. + +Custom tools default to sequential execution. To enable parallel execution for a custom tool, mark it as read-only in its annotations: `readOnly` in [TypeScript](/en/agent-sdk/typescript#tool) or `readOnlyHint` in [Python](/en/agent-sdk/python#tool). + +## Control how the loop runs + +You can limit how many turns the loop takes, how much it costs, how deeply Claude reasons, and whether tools require approval before running. All of these are fields on [`ClaudeAgentOptions`](/en/agent-sdk/python#claude-agent-options) (Python) / [`Options`](/en/agent-sdk/typescript#options) (TypeScript). + +### Turns and budget + +| Option | What it controls | Default | +| :--------------------------------------------- | :--------------------------- | :------- | +| Max turns (`max_turns` / `maxTurns`) | Maximum tool-use round trips | No limit | +| Max budget (`max_budget_usd` / `maxBudgetUsd`) | Maximum cost before stopping | No limit | + +When either limit is hit, the SDK returns a `ResultMessage` with a corresponding error subtype (`error_max_turns` or `error_max_budget_usd`). See [Handle the result](#handle-the-result) for how to check these subtypes and [`ClaudeAgentOptions`](/en/agent-sdk/python#claude-agent-options) / [`Options`](/en/agent-sdk/typescript#options) for syntax. + +### Effort level + +The `effort` option controls how much reasoning Claude applies. Lower effort levels use fewer tokens per turn and reduce cost. Not all models support the effort parameter. See [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) for which models support it. + +| Level | Behavior | Good for | +| :--------- | :-------------------------------- | :------------------------------------------ | +| `"low"` | Minimal reasoning, fast responses | File lookups, listing directories | +| `"medium"` | Balanced reasoning | Routine edits, standard tasks | +| `"high"` | Thorough analysis | Refactors, debugging | +| `"max"` | Maximum reasoning depth | Multi-step problems requiring deep analysis | + +If you don't set `effort`, the Python SDK leaves the parameter unset and defers to the model's default behavior. The TypeScript SDK defaults to `"high"`. + + + `effort` trades latency and token cost for reasoning depth within each response. [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) is a separate feature that produces visible chain-of-thought blocks in the output. They are independent: you can set `effort: "low"` with extended thinking enabled, or `effort: "max"` without it. + + +Use lower effort for agents doing simple, well-scoped tasks (like listing files or running a single grep) to reduce cost and latency. `effort` is set at the top-level `query()` options, not per-subagent. + +### Permission mode + +The permission mode option (`permission_mode` in Python, `permissionMode` in TypeScript) controls whether the agent asks for approval before using tools: + +| Mode | Behavior | +| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `"default"` | Tools not covered by allow rules trigger your approval callback; no callback means deny | +| `"acceptEdits"` | Auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.); other Bash commands follow default rules | +| `"plan"` | No tool execution; Claude produces a plan for review | +| `"dontAsk"` | Never prompts. Tools pre-approved by [permission rules](/en/settings#permission-settings) run, everything else is denied | +| `"auto"` (TypeScript only) | Uses a model classifier to approve or deny each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability and behavior | +| `"bypassPermissions"` | Runs all allowed tools without asking. Cannot be used when running as root on Unix. Use only in isolated environments where the agent's actions cannot affect systems you care about | + +For interactive applications, use `"default"` with a tool approval callback to surface approval prompts. For autonomous agents on a dev machine, `"acceptEdits"` auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.) while still gating other `Bash` commands behind allow rules. Reserve `"bypassPermissions"` for CI, containers, or other isolated environments. See [Permissions](/en/agent-sdk/permissions) for full details. + +### Model + +If you don't set `model`, the SDK uses Claude Code's default, which depends on your authentication method and subscription. Set it explicitly (for example, `model="claude-sonnet-4-6"`) to pin a specific model or to use a smaller model for faster, cheaper agents. See [models](https://platform.claude.com/docs/en/about-claude/models) for available IDs. + +## The context window + +The context window is the total amount of information available to Claude during a session. It does not reset between turns within a session. Everything accumulates: the system prompt, tool definitions, conversation history, tool inputs, and tool outputs. Content that stays the same across turns (system prompt, tool definitions, CLAUDE.md) is automatically [prompt cached](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), which reduces cost and latency for repeated prefixes. + +### What consumes context + +Here's how each component affects context in the SDK: + +| Source | When it loads | Impact | +| :----------------------- | :------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------- | +| **System prompt** | Every request | Small fixed cost, always present | +| **CLAUDE.md files** | Session start, when [`settingSources`](/en/agent-sdk/claude-code-features) is enabled | Full content in every request (but prompt-cached, so only the first request pays full cost) | +| **Tool definitions** | Every request | Each tool adds its schema; use [MCP tool search](/en/agent-sdk/mcp#mcp-tool-search) to load tools on-demand instead of all at once | +| **Conversation history** | Accumulates over turns | Grows with each turn: prompts, responses, tool inputs, tool outputs | +| **Skill descriptions** | Session start (with setting sources enabled) | Short summaries; full content loads only when invoked | + +Large tool outputs consume significant context. Reading a big file or running a command with verbose output can use thousands of tokens in a single turn. Context accumulates across turns, so longer sessions with many tool calls build up significantly more context than short ones. + +### Automatic compaction + +When the context window approaches its limit, the SDK automatically compacts the conversation: it summarizes older history to free space, keeping your most recent exchanges and key decisions intact. The SDK emits a message with `type: "system"` and `subtype: "compact_boundary"` in the stream when this happens (in Python this is a `SystemMessage`; in TypeScript it is a separate `SDKCompactBoundaryMessage` type). + +Compaction replaces older messages with a summary, so specific instructions from early in the conversation may not be preserved. Persistent rules belong in CLAUDE.md (loaded via [`settingSources`](/en/agent-sdk/claude-code-features)) rather than in the initial prompt, because CLAUDE.md content is re-injected on every request. + +You can customize compaction behavior in several ways: + +* **Summarization instructions in CLAUDE.md:** The compactor reads your CLAUDE.md like any other context, so you can include a section telling it what to preserve when summarizing. The section header is free-form (not a magic string); the compactor matches on intent. +* **`PreCompact` hook:** Run custom logic before compaction occurs, for example to archive the full transcript. The hook receives a `trigger` field (`manual` or `auto`). See [hooks](/en/agent-sdk/hooks). +* **Manual compaction:** Send `/compact` as a prompt string to trigger compaction on demand. (Slash commands sent this way are SDK inputs, not CLI-only shortcuts. See [slash commands in the SDK](/en/agent-sdk/slash-commands).) + + + Add a section to your project's CLAUDE.md telling the compactor what to preserve. The header name isn't special; use any clear label. + + ```markdown CLAUDE.md theme={null} + # Summary instructions + + When summarizing this conversation, always preserve: + - The current task objective and acceptance criteria + - File paths that have been read or modified + - Test results and error messages + - Decisions made and the reasoning behind them + ``` + + +### Keep context efficient + +A few strategies for long-running agents: + +* **Use subagents for subtasks.** Each subagent starts with a fresh conversation (no prior message history, though it does load its own system prompt and project-level context like CLAUDE.md). It does not see the parent's turns, and only its final response returns to the parent as a tool result. The main agent's context grows by that summary, not by the full subtask transcript. See [What subagents inherit](/en/agent-sdk/subagents#what-subagents-inherit) for details. +* **Be selective with tools.** Every tool definition takes context space. Use the `tools` field on [`AgentDefinition`](/en/agent-sdk/subagents#agent-definition-configuration) to scope subagents to the minimum set they need, and use [MCP tool search](/en/agent-sdk/mcp#mcp-tool-search) to load tools on demand instead of preloading all of them. +* **Watch MCP server costs.** Each MCP server adds all its tool schemas to every request. A few servers with many tools can consume significant context before the agent does any work. The `ToolSearch` tool can help by loading tools on-demand instead of preloading all of them. See [MCP tool search](/en/agent-sdk/mcp#mcp-tool-search) for configuration. +* **Use lower effort for routine tasks.** Set [effort](#effort-level) to `"low"` for agents that only need to read files or list directories. This reduces token usage and cost. + +For a detailed breakdown of per-feature context costs, see [Understand context costs](/en/features-overview#understand-context-costs). + +## Sessions and continuity + +Each interaction with the SDK creates or continues a session. Capture the session ID from `ResultMessage.session_id` (available in both SDKs) to resume later. The TypeScript SDK also exposes it as a direct field on the init `SystemMessage`; in Python it's nested in `SystemMessage.data`. + +When you resume, the full context from previous turns is restored: files that were read, analysis that was performed, and actions that were taken. You can also fork a session to branch into a different approach without modifying the original. + +See [Session management](/en/agent-sdk/sessions) for the full guide on resume, continue, and fork patterns. + + + In Python, `ClaudeSDKClient` handles session IDs automatically across multiple calls. See the [Python SDK reference](/en/agent-sdk/python#choosing-between-query-and-claude-sdk-client) for details. + + +## Handle the result + +When the loop ends, the `ResultMessage` tells you what happened and gives you the output. The `subtype` field (available in both SDKs) is the primary way to check termination state. + +| Result subtype | What happened | `result` field available? | +| :------------------------------------ | :------------------------------------------------------------------------------- | :-----------------------: | +| `success` | Claude finished the task normally | Yes | +| `error_max_turns` | Hit the `maxTurns` limit before finishing | No | +| `error_max_budget_usd` | Hit the `maxBudgetUsd` limit before finishing | No | +| `error_during_execution` | An error interrupted the loop (for example, an API failure or cancelled request) | No | +| `error_max_structured_output_retries` | Structured output validation failed after the configured retry limit | No | + +The `result` field (the final text output) is only present on the `success` variant, so always check the subtype before reading it. All result subtypes carry `total_cost_usd`, `usage`, `num_turns`, and `session_id` so you can track cost and resume even after errors. In Python, `total_cost_usd` and `usage` are typed as optional and may be `None` on some error paths, so guard before formatting them. See [Tracking costs and usage](/en/agent-sdk/cost-tracking) for details on interpreting the `usage` fields. + +The result also includes a `stop_reason` field (`string | null` in TypeScript, `str | None` in Python) indicating why the model stopped generating on its final turn. Common values are `end_turn` (model finished normally), `max_tokens` (hit the output token limit), and `refusal` (the model declined the request). On error result subtypes, `stop_reason` carries the value from the last assistant response before the loop ended. To detect refusals, check `stop_reason === "refusal"` (TypeScript) or `stop_reason == "refusal"` (Python). See [`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message) (TypeScript) or [`ResultMessage`](/en/agent-sdk/python#result-message) (Python) for the full type. + +## Hooks + +[Hooks](/en/agent-sdk/hooks) are callbacks that fire at specific points in the loop: before a tool runs, after it returns, when the agent finishes, and so on. Some commonly used hooks are: + +| Hook | When it fires | Common uses | +| :------------------------------- | :---------------------------------- | :----------------------------------------- | +| `PreToolUse` | Before a tool executes | Validate inputs, block dangerous commands | +| `PostToolUse` | After a tool returns | Audit outputs, trigger side effects | +| `UserPromptSubmit` | When a prompt is sent | Inject additional context into prompts | +| `Stop` | When the agent finishes | Validate the result, save session state | +| `SubagentStart` / `SubagentStop` | When a subagent spawns or completes | Track and aggregate parallel task results | +| `PreCompact` | Before context compaction | Archive full transcript before summarizing | + +Hooks run in your application process, not inside the agent's context window, so they don't consume context. Hooks can also short-circuit the loop: a `PreToolUse` hook that rejects a tool call prevents it from executing, and Claude receives the rejection message instead. + +Both SDKs support all the events above. The TypeScript SDK includes additional events that Python does not yet support. See [Control execution with hooks](/en/agent-sdk/hooks) for the complete event list, per-SDK availability, and the full callback API. + +## Put it all together + +This example combines the key concepts from this page into a single agent that fixes failing tests. It configures the agent with allowed tools (auto-approved so the agent runs autonomously), project settings, and safety limits on turns and reasoning effort. As the loop runs, it captures the session ID for potential resumption, handles the final result, and prints the total cost. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + + async def run_agent(): + session_id = None + + async for message in query( + prompt="Find and fix the bug causing test failures in the auth module", + options=ClaudeAgentOptions( + allowed_tools=[ + "Read", + "Edit", + "Bash", + "Glob", + "Grep", + ], # Listing tools here auto-approves them (no prompting) + setting_sources=[ + "project" + ], # Load CLAUDE.md, skills, hooks from current directory + max_turns=30, # Prevent runaway sessions + effort="high", # Thorough reasoning for complex debugging + ), + ): + # Handle the final result + if isinstance(message, ResultMessage): + session_id = message.session_id # Save for potential resumption + + if message.subtype == "success": + print(f"Done: {message.result}") + elif message.subtype == "error_max_turns": + # Agent ran out of turns. Resume with a higher limit. + print(f"Hit turn limit. Resume session {session_id} to continue.") + elif message.subtype == "error_max_budget_usd": + print("Hit budget limit.") + else: + print(f"Stopped: {message.subtype}") + if message.total_cost_usd is not None: + print(f"Cost: ${message.total_cost_usd:.4f}") + + + asyncio.run(run_agent()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + let sessionId: string | undefined; + + for await (const message of query({ + prompt: "Find and fix the bug causing test failures in the auth module", + options: { + allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting) + settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory + maxTurns: 30, // Prevent runaway sessions + effort: "high" // Thorough reasoning for complex debugging + } + })) { + // Save the session ID to resume later if needed + if (message.type === "system" && message.subtype === "init") { + sessionId = message.session_id; + } + + // Handle the final result + if (message.type === "result") { + if (message.subtype === "success") { + console.log(`Done: ${message.result}`); + } else if (message.subtype === "error_max_turns") { + // Agent ran out of turns. Resume with a higher limit. + console.log(`Hit turn limit. Resume session ${sessionId} to continue.`); + } else if (message.subtype === "error_max_budget_usd") { + console.log("Hit budget limit."); + } else { + console.log(`Stopped: ${message.subtype}`); + } + console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`); + } + } + ``` + + +## Next steps + +Now that you understand the loop, here's where to go depending on what you're building: + +* **Haven't run an agent yet?** Start with the [quickstart](/en/agent-sdk/quickstart) to get the SDK installed and see a full example running end to end. +* **Ready to hook into your project?** [Load CLAUDE.md, skills, and filesystem hooks](/en/agent-sdk/claude-code-features) so the agent follows your project conventions automatically. +* **Building an interactive UI?** Enable [streaming](/en/agent-sdk/streaming-output) to show live text and tool calls as the loop runs. +* **Need tighter control over what the agent can do?** Lock down tool access with [permissions](/en/agent-sdk/permissions), and use [hooks](/en/agent-sdk/hooks) to audit, block, or transform tool calls before they execute. +* **Running long or expensive tasks?** Offload isolated work to [subagents](/en/agent-sdk/subagents) to keep your main context lean. + +For the broader conceptual picture of the agentic loop (not SDK-specific), see [How Claude Code works](/en/how-claude-code-works). diff --git a/content/en/docs/claude-code/agent-sdk/claude-code-features.md b/content/en/docs/claude-code/agent-sdk/claude-code-features.md new file mode 100644 index 000000000..34ed660ad --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/claude-code-features.md @@ -0,0 +1,271 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Use Claude Code features in the SDK + +> Load project instructions, skills, hooks, and other Claude Code features into your SDK agents. + +The Agent SDK is built on the same foundation as Claude Code, which means your SDK agents have access to the same filesystem-based features: project instructions (`CLAUDE.md` and rules), skills, hooks, and more. + +By default, the SDK loads no filesystem settings. Your agent runs in isolation mode with only what you pass programmatically. To load CLAUDE.md, skills, or filesystem hooks, set `settingSources` to tell the SDK where to look. + +For a conceptual overview of what each feature does and when to use it, see [Extend Claude Code](/en/features-overview). + +## Enable Claude Code features with settingSources + +The setting sources option ([`setting_sources`](/en/agent-sdk/python#claude-agent-options) in Python, [`settingSources`](/en/agent-sdk/typescript#setting-source) in TypeScript) controls which filesystem-based settings the SDK loads. Without it, your agent won't discover skills, `CLAUDE.md` files, or project-level hooks. + +This example loads both user-level and project-level settings by setting `settingSources` to `["user", "project"]`: + + + ```python Python theme={null} + from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage + + async for message in query( + prompt="Help me refactor the auth module", + options=ClaudeAgentOptions( + # "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd. + # Together they give the agent access to CLAUDE.md, skills, hooks, and + # permissions from both locations. + setting_sources=["user", "project"], + allowed_tools=["Read", "Edit", "Bash"], + ), + ): + if isinstance(message, AssistantMessage): + for block in message.content: + if hasattr(block, "text"): + print(block.text) + if isinstance(message, ResultMessage) and message.subtype == "success": + print(f"\nResult: {message.result}") + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Help me refactor the auth module", + options: { + // "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd. + // Together they give the agent access to CLAUDE.md, skills, hooks, and + // permissions from both locations. + settingSources: ["user", "project"], + allowedTools: ["Read", "Edit", "Bash"] + } + })) { + if (message.type === "assistant") { + for (const block of message.message.content) { + if (block.type === "text") console.log(block.text); + } + } + if (message.type === "result" && message.subtype === "success") { + console.log(`\nResult: ${message.result}`); + } + } + ``` + + +Each source loads settings from a specific location, where `` is the working directory you pass via the `cwd` option (or the process's current directory if unset). For the full type definition, see [`SettingSource`](/en/agent-sdk/typescript#setting-source) (TypeScript) or [`SettingSource`](/en/agent-sdk/python#setting-source) (Python). + +| Source | What it loads | Location | +| :---------- | :---------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | +| `"project"` | Project CLAUDE.md, `.claude/rules/*.md`, project skills, project hooks, project `settings.json` | `/.claude/` and each parent directory up to the filesystem root (stopping when a `.claude/` is found or no more parents exist) | +| `"user"` | User CLAUDE.md, `~/.claude/rules/*.md`, user skills, user settings | `~/.claude/` | +| `"local"` | CLAUDE.local.md (gitignored), `.claude/settings.local.json` | `/` | + +To match the full Claude Code CLI behavior, use `["user", "project", "local"]`. + + + The `cwd` option determines where the SDK looks for project settings. If neither `cwd` nor any of its parent directories contains a `.claude/` folder, project-level features won't load. Auto memory (the `~/.claude/projects//memory/` directory that Claude Code uses to persist notes across interactive sessions) is a CLI-only feature and is never loaded by the SDK. + + +## Project instructions (CLAUDE.md and rules) + +`CLAUDE.md` files and `.claude/rules/*.md` files give your agent persistent context about your project: coding conventions, build commands, architecture decisions, and instructions. When `settingSources` includes `"project"` (as in the example above), the SDK loads these files into context at session start. The agent then follows your project conventions without you repeating them in every prompt. + +### CLAUDE.md load locations + +| Level | Location | When loaded | +| :-------------------- | :--------------------------------------------- | :-------------------------------------------------------------------------------------------------- | +| Project (root) | `/CLAUDE.md` or `/.claude/CLAUDE.md` | `settingSources` includes `"project"` | +| Project rules | `/.claude/rules/*.md` | `settingSources` includes `"project"` | +| Project (parent dirs) | `CLAUDE.md` files in directories above `cwd` | `settingSources` includes `"project"`, loaded at session start | +| Project (child dirs) | `CLAUDE.md` files in subdirectories of `cwd` | `settingSources` includes `"project"`, loaded on demand when the agent reads a file in that subtree | +| Local (gitignored) | `/CLAUDE.local.md` | `settingSources` includes `"local"` | +| User | `~/.claude/CLAUDE.md` | `settingSources` includes `"user"` | +| User rules | `~/.claude/rules/*.md` | `settingSources` includes `"user"` | + +All levels are additive: if both project and user CLAUDE.md files exist, the agent sees both. There is no hard precedence rule between levels; if instructions conflict, the outcome depends on how Claude interprets them. Write non-conflicting rules, or state precedence explicitly in the more specific file ("These project instructions override any conflicting user-level defaults"). + + + You can also inject context directly via `systemPrompt` without using CLAUDE.md files. See [Modify system prompts](/en/agent-sdk/modifying-system-prompts). Use CLAUDE.md when you want the same context shared between interactive Claude Code sessions and your SDK agents. + + +For how to structure and organize CLAUDE.md content, see [Manage Claude's memory](/en/memory). + +## Skills + +Skills are markdown files that give your agent specialized knowledge and invocable workflows. Unlike `CLAUDE.md` (which loads every session), skills load on demand. The agent receives skill descriptions at startup and loads the full content when relevant. + +To use skills in the SDK, set `settingSources` so the agent discovers skill files from the filesystem. The `Skill` tool is enabled by default when you don't specify `allowedTools`. If you are using an `allowedTools` allowlist, include `"Skill"` explicitly. + + + ```python Python theme={null} + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + # Skills in .claude/skills/ are discovered automatically + # when settingSources includes "project" + async for message in query( + prompt="Review this PR using our code review checklist", + options=ClaudeAgentOptions( + setting_sources=["user", "project"], + allowed_tools=["Skill", "Read", "Grep", "Glob"], + ), + ): + if isinstance(message, ResultMessage) and message.subtype == "success": + print(message.result) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Skills in .claude/skills/ are discovered automatically + // when settingSources includes "project" + for await (const message of query({ + prompt: "Review this PR using our code review checklist", + options: { + settingSources: ["user", "project"], + allowedTools: ["Skill", "Read", "Grep", "Glob"] + } + })) { + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } + } + ``` + + + + Skills must be created as filesystem artifacts (`.claude/skills//SKILL.md`). The SDK does not have a programmatic API for registering skills. See [Agent Skills in the SDK](/en/agent-sdk/skills) for full details. + + +For more on creating and using skills, see [Agent Skills in the SDK](/en/agent-sdk/skills). + +## Hooks + +The SDK supports two ways to define hooks, and they run side by side: + +* **Filesystem hooks:** shell commands defined in `settings.json`, loaded when `settingSources` includes the relevant source. These are the same hooks you'd configure for [interactive Claude Code sessions](/en/hooks-guide). +* **Programmatic hooks:** callback functions passed directly to `query()`. These run in your application process and can return structured decisions. See [Control execution with hooks](/en/agent-sdk/hooks). + +Both types execute during the same hook lifecycle. If you already have hooks in your project's `.claude/settings.json` and you set `settingSources: ["project"]`, those hooks run automatically in the SDK with no extra configuration. + +Hook callbacks receive the tool input and return a decision dict. Returning `{}` (an empty dict) means allow the tool to proceed. Returning `{"decision": "block", "reason": "..."}` prevents execution and the reason is sent to Claude as the tool result. See the [hooks guide](/en/agent-sdk/hooks) for the full callback signature and return types. + + + ```python Python theme={null} + from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage + + + # PreToolUse hook callback. Positional args: + # input_data: HookInput dict with tool_name, tool_input, hook_event_name + # tool_use_id: str | None, the ID of the tool call being intercepted + # context: HookContext, carries session metadata + async def audit_bash(input_data, tool_use_id, context): + command = input_data.get("tool_input", {}).get("command", "") + if "rm -rf" in command: + return {"decision": "block", "reason": "Destructive command blocked"} + return {} # Empty dict: allow the tool to proceed + + + # Filesystem hooks from .claude/settings.json run automatically + # when settingSources loads them. You can also add programmatic hooks: + async for message in query( + prompt="Refactor the auth module", + options=ClaudeAgentOptions( + setting_sources=["project"], # Loads hooks from .claude/settings.json + hooks={ + "PreToolUse": [ + HookMatcher(matcher="Bash", hooks=[audit_bash]), + ] + }, + ), + ): + if isinstance(message, ResultMessage) and message.subtype == "success": + print(message.result) + ``` + + ```typescript TypeScript theme={null} + import { query, type HookInput, type HookJSONOutput } from "@anthropic-ai/claude-agent-sdk"; + + // PreToolUse hook callback. HookInput is a discriminated union on + // hook_event_name, so narrowing on it gives TypeScript the right + // tool_input shape for this event. + const auditBash = async (input: HookInput): Promise => { + if (input.hook_event_name !== "PreToolUse") return {}; + const toolInput = input.tool_input as { command?: string }; + if (toolInput.command?.includes("rm -rf")) { + return { decision: "block", reason: "Destructive command blocked" }; + } + return {}; // Empty object: allow the tool to proceed + }; + + // Filesystem hooks from .claude/settings.json run automatically + // when settingSources loads them. You can also add programmatic hooks: + for await (const message of query({ + prompt: "Refactor the auth module", + options: { + settingSources: ["project"], // Loads hooks from .claude/settings.json + hooks: { + PreToolUse: [{ matcher: "Bash", hooks: [auditBash] }] + } + } + })) { + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } + } + ``` + + +### When to use which hook type + +| Hook type | Best for | +| :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Filesystem** (`settings.json`) | Sharing hooks between CLI and SDK sessions. Supports `"command"` (shell scripts), `"http"` (POST to an endpoint), `"prompt"` (LLM evaluates a prompt), and `"agent"` (spawns a verifier agent). These fire in the main agent and any subagents it spawns. | +| **Programmatic** (callbacks in `query()`) | Application-specific logic; returning structured decisions; in-process integration. Scoped to the main session only. | + + + The TypeScript SDK supports additional hook events beyond Python, including `SessionStart`, `SessionEnd`, `TeammateIdle`, and `TaskCompleted`. See the [hooks guide](/en/agent-sdk/hooks) for the full event compatibility table. + + +For full details on programmatic hooks, see [Control execution with hooks](/en/agent-sdk/hooks). For filesystem hook syntax, see [Hooks](/en/hooks). + +## Choose the right feature + +The Agent SDK gives you access to several ways to extend your agent's behavior. If you're unsure which to use, this table maps common goals to the right approach. + +| You want to... | Use | SDK surface | +| :------------------------------------------------------------------------------------------------ | :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Set project conventions your agent always follows | [CLAUDE.md](/en/memory) | `settingSources: ["project"]` loads it automatically | +| Give the agent reference material it loads when relevant | [Skills](/en/agent-sdk/skills) | `settingSources` + `allowedTools: ["Skill"]` | +| Run a reusable workflow (deploy, review, release) | [User-invocable skills](/en/agent-sdk/skills) | `settingSources` + `allowedTools: ["Skill"]` | +| Delegate an isolated subtask to a fresh context (research, review) | [Subagents](/en/agent-sdk/subagents) | `agents` parameter + `allowedTools: ["Agent"]` | +| Coordinate multiple Claude Code instances with shared task lists and direct inter-agent messaging | [Agent teams](/en/agent-teams) | Not directly configured via SDK options. Agent teams are a CLI feature where one session acts as the team lead, coordinating work across independent teammates | +| Run deterministic logic on tool calls (audit, block, transform) | [Hooks](/en/agent-sdk/hooks) | `hooks` parameter with callbacks, or shell scripts loaded via `settingSources` | +| Give Claude structured tool access to an external service | [MCP](/en/agent-sdk/mcp) | `mcpServers` parameter | + + + **Subagents versus agent teams:** Subagents are ephemeral and isolated: fresh conversation, one task, summary returned to parent. Agent teams coordinate multiple independent Claude Code instances that share a task list and message each other directly. Agent teams are a CLI feature. See [What subagents inherit](/en/agent-sdk/subagents#what-subagents-inherit) and the [agent teams comparison](/en/agent-teams#compare-with-subagents) for details. + + +Every feature you enable adds to your agent's context window. For per-feature costs and how these features layer together, see [Extend Claude Code](/en/features-overview#understand-context-costs). + +## Related resources + +* [Extend Claude Code](/en/features-overview): Conceptual overview of all extension features, with comparison tables and context cost analysis +* [Skills in the SDK](/en/agent-sdk/skills): Full guide to using skills programmatically +* [Subagents](/en/agent-sdk/subagents): Define and invoke subagents for isolated subtasks +* [Hooks](/en/agent-sdk/hooks): Intercept and control agent behavior at key execution points +* [Permissions](/en/agent-sdk/permissions): Control tool access with modes, rules, and callbacks +* [System prompts](/en/agent-sdk/modifying-system-prompts): Inject context without CLAUDE.md files diff --git a/content/en/docs/claude-code/agent-sdk/cost-tracking.md b/content/en/docs/claude-code/agent-sdk/cost-tracking.md new file mode 100644 index 000000000..b3595bd7c --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/cost-tracking.md @@ -0,0 +1,222 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Track cost and usage + +> Learn how to track token usage, deduplicate parallel tool calls, and calculate costs with the Claude Agent SDK. + +The Claude Agent SDK provides detailed token usage information for each interaction with Claude. This guide explains how to properly track costs and understand usage reporting, especially when dealing with parallel tool uses and multi-step conversations. + +For complete API documentation, see the [TypeScript SDK reference](/en/agent-sdk/typescript) and [Python SDK reference](/en/agent-sdk/python). + +## Understand token usage + +The TypeScript and Python SDKs expose the same usage data with different field names: + +* **TypeScript** provides per-step token breakdowns on each assistant message (`message.message.id`, `message.message.usage`), per-model cost via `modelUsage` on the result message, and a cumulative total on the result message. +* **Python** provides per-step token breakdowns on each assistant message (`message.usage`, `message.message_id`), per-model cost via `model_usage` on the result message, and the accumulated total on the result message (`total_cost_usd` and `usage` dict). + +Both SDKs use the same underlying cost model and expose the same granularity. The difference is in field naming and where per-step usage is nested. + +Cost tracking depends on understanding how the SDK scopes usage data: + +* **`query()` call:** one invocation of the SDK's `query()` function. A single call can involve multiple steps (Claude responds, uses tools, gets results, responds again). Each call produces one [`result`](/en/agent-sdk/typescript#sdk-result-message) message at the end. +* **Step:** a single request/response cycle within a `query()` call. Each step produces assistant messages with token usage. +* **Session:** a series of `query()` calls linked by a session ID (using the `resume` option). Each `query()` call within a session reports its own cost independently. + +The following diagram shows the message stream from a single `query()` call, with token usage reported at each step and the authoritative total at the end: + +Diagram showing a query producing two steps of messages. Step 1 has four assistant messages sharing the same ID and usage (count once), Step 2 has one assistant message with a new ID, and the final result message shows total_cost_usd for billing. + + + + When Claude responds, it sends one or more assistant messages. In TypeScript, each assistant message contains a nested `BetaMessage` (accessed via `message.message`) with an `id` and a [`usage`](https://platform.claude.com/docs/en/api/messages) object with token counts (`input_tokens`, `output_tokens`). In Python, the `AssistantMessage` dataclass exposes the same data directly via `message.usage` and `message.message_id`. When Claude uses multiple tools in one turn, all messages in that turn share the same ID, so deduplicate by ID to avoid double-counting. + + + + When the `query()` call completes, the SDK emits a result message with `total_cost_usd` and cumulative `usage`. This is available in both TypeScript ([`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message)) and Python ([`ResultMessage`](/en/agent-sdk/python#result-message)). If you make multiple `query()` calls (for example, in a multi-turn session), each result only reflects the cost of that individual call. If you only need the total cost, you can ignore the per-step usage and read this single value. + + + +## Get the total cost of a query + +The result message ([TypeScript](/en/agent-sdk/typescript#sdk-result-message), [Python](/en/agent-sdk/python#result-message)) is the last message in every `query()` call. It includes `total_cost_usd`, the cumulative cost across all steps in that call. This works for both success and error results. If you use sessions to make multiple `query()` calls, each result only reflects the cost of that individual call. + +The following examples iterate over the message stream from a `query()` call and print the total cost when the `result` message arrives: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ prompt: "Summarize this project" })) { + if (message.type === "result") { + console.log(`Total cost: $${message.total_cost_usd}`); + } + } + ``` + + ```python Python theme={null} + from claude_agent_sdk import query, ResultMessage + import asyncio + + + async def main(): + async for message in query(prompt="Summarize this project"): + if isinstance(message, ResultMessage): + print(f"Total cost: ${message.total_cost_usd or 0}") + + + asyncio.run(main()) + ``` + + +## Track per-step and per-model usage + +The examples in this section use TypeScript field names. In Python, the equivalent fields are [`AssistantMessage.usage`](/en/agent-sdk/python#assistant-message) and `AssistantMessage.message_id` for per-step usage, and [`ResultMessage.model_usage`](/en/agent-sdk/python#result-message) for per-model breakdowns. + +### Track per-step usage + +Each assistant message contains a nested `BetaMessage` (accessed via `message.message`) with an `id` and `usage` object with token counts. When Claude uses tools in parallel, multiple messages share the same `id` with identical usage data. Track which IDs you've already counted and skip duplicates to avoid inflated totals. + + + Parallel tool calls produce multiple assistant messages whose nested `BetaMessage` shares the same `id` and identical usage. Always deduplicate by ID to get accurate per-step token counts. + + +The following example accumulates input and output tokens across all steps, counting each unique message ID only once: + +```typescript theme={null} +import { query } from "@anthropic-ai/claude-agent-sdk"; + +const seenIds = new Set(); +let totalInputTokens = 0; +let totalOutputTokens = 0; + +for await (const message of query({ prompt: "Summarize this project" })) { + if (message.type === "assistant") { + const msgId = message.message.id; + + // Parallel tool calls share the same ID, only count once + if (!seenIds.has(msgId)) { + seenIds.add(msgId); + totalInputTokens += message.message.usage.input_tokens; + totalOutputTokens += message.message.usage.output_tokens; + } + } +} + +console.log(`Steps: ${seenIds.size}`); +console.log(`Input tokens: ${totalInputTokens}`); +console.log(`Output tokens: ${totalOutputTokens}`); +``` + +### Break down usage per model + +The result message includes [`modelUsage`](/en/agent-sdk/typescript#model-usage), a map of model name to per-model token counts and cost. This is useful when you run multiple models (for example, Haiku for subagents and Opus for the main agent) and want to see where tokens are going. + +The following example runs a query and prints the cost and token breakdown for each model used: + +```typescript theme={null} +import { query } from "@anthropic-ai/claude-agent-sdk"; + +for await (const message of query({ prompt: "Summarize this project" })) { + if (message.type !== "result") continue; + + for (const [modelName, usage] of Object.entries(message.modelUsage)) { + console.log(`${modelName}: $${usage.costUSD.toFixed(4)}`); + console.log(` Input tokens: ${usage.inputTokens}`); + console.log(` Output tokens: ${usage.outputTokens}`); + console.log(` Cache read: ${usage.cacheReadInputTokens}`); + console.log(` Cache creation: ${usage.cacheCreationInputTokens}`); + } +} +``` + +## Accumulate costs across multiple calls + +Each `query()` call returns its own `total_cost_usd`. The SDK does not provide a session-level total, so if your application makes multiple `query()` calls (for example, in a multi-turn session or across different users), accumulate the totals yourself. + +The following examples run two `query()` calls sequentially, add each call's `total_cost_usd` to a running total, and print both the per-call and combined cost: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Track cumulative cost across multiple query() calls + let totalSpend = 0; + + const prompts = [ + "Read the files in src/ and summarize the architecture", + "List all exported functions in src/auth.ts" + ]; + + for (const prompt of prompts) { + for await (const message of query({ prompt })) { + if (message.type === "result") { + totalSpend += message.total_cost_usd; + console.log(`This call: $${message.total_cost_usd}`); + } + } + } + + console.log(`Total spend: $${totalSpend.toFixed(4)}`); + ``` + + ```python Python theme={null} + from claude_agent_sdk import query, ResultMessage + import asyncio + + + async def main(): + # Track cumulative cost across multiple query() calls + total_spend = 0.0 + + prompts = [ + "Read the files in src/ and summarize the architecture", + "List all exported functions in src/auth.ts", + ] + + for prompt in prompts: + async for message in query(prompt=prompt): + if isinstance(message, ResultMessage): + cost = message.total_cost_usd or 0 + total_spend += cost + print(f"This call: ${cost}") + + print(f"Total spend: ${total_spend:.4f}") + + + asyncio.run(main()) + ``` + + +## Handle errors, caching, and token discrepancies + +For accurate cost tracking, account for failed conversations, cache token pricing, and occasional reporting inconsistencies. + +### Resolve output token discrepancies + +In rare cases, you might observe different `output_tokens` values for messages with the same ID. When this occurs: + +1. **Use the highest value:** the final message in a group typically contains the accurate total. +2. **Verify against total cost:** the `total_cost_usd` in the result message is authoritative. +3. **Report inconsistencies:** file issues at the [Claude Code GitHub repository](https://github.com/anthropics/claude-code/issues). + +### Track costs on failed conversations + +Both success and error result messages include `usage` and `total_cost_usd`. If a conversation fails mid-way, you still consumed tokens up to the point of failure. Always read cost data from the result message regardless of its `subtype`. + +### Track cache tokens + +The Agent SDK automatically uses [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) to reduce costs on repeated content. You do not need to configure caching yourself. The usage object includes two additional fields for cache tracking: + +* `cache_creation_input_tokens`: tokens used to create new cache entries (charged at a higher rate than standard input tokens). +* `cache_read_input_tokens`: tokens read from existing cache entries (charged at a reduced rate). + +Track these separately from `input_tokens` to understand caching savings. In TypeScript, these fields are typed on the [`Usage`](/en/agent-sdk/typescript#usage) object. In Python, they appear as keys in the [`ResultMessage.usage`](/en/agent-sdk/python#result-message) dict (for example, `message.usage.get("cache_read_input_tokens", 0)`). + +## Related documentation + +* [TypeScript SDK Reference](/en/agent-sdk/typescript) - Complete API documentation +* [SDK Overview](/en/agent-sdk/overview) - Getting started with the SDK +* [SDK Permissions](/en/agent-sdk/permissions) - Managing tool permissions diff --git a/content/en/docs/claude-code/agent-sdk/custom-tools.md b/content/en/docs/claude-code/agent-sdk/custom-tools.md new file mode 100644 index 000000000..83b47510a --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/custom-tools.md @@ -0,0 +1,804 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Give Claude custom tools + +> Define custom tools with the Claude Agent SDK's in-process MCP server so Claude can call your functions, hit your APIs, and perform domain-specific operations. + +Custom tools extend the Agent SDK by letting you define your own functions that Claude can call during a conversation. Using the SDK's in-process MCP server, you can give Claude access to databases, external APIs, domain-specific logic, or any other capability your application needs. + +This guide covers how to define tools with input schemas and handlers, bundle them into an MCP server, pass them to `query`, and control which tools Claude can access. It also covers error handling, tool annotations, and returning non-text content like images. + +## Quick reference + +| If you want to... | Do this | +| :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Define a tool | Use [`@tool`](/en/agent-sdk/python#tool) (Python) or [`tool()`](/en/agent-sdk/typescript#tool) (TypeScript) with a name, description, schema, and handler. See [Create a custom tool](#create-a-custom-tool). | +| Register a tool with Claude | Wrap in `create_sdk_mcp_server` / `createSdkMcpServer` and pass to `mcpServers` in `query()`. See [Call a custom tool](#call-a-custom-tool). | +| Pre-approve a tool | Add to your allowed tools. See [Configure allowed tools](#configure-allowed-tools). | +| Remove a built-in tool from Claude's context | Pass a `tools` array listing only the built-ins you want. See [Configure allowed tools](#configure-allowed-tools). | +| Let Claude call tools in parallel | Set `readOnlyHint: true` on tools with no side effects. See [Add tool annotations](#add-tool-annotations). | +| Handle errors without stopping the loop | Return `isError: true` instead of throwing. See [Handle errors](#handle-errors). | +| Return images or files | Use `image` or `resource` blocks in the content array. See [Return images and resources](#return-images-and-resources). | +| Scale to many tools | Use [tool search](/en/agent-sdk/tool-search) to load tools on demand. | + +## Create a custom tool + +A tool is defined by four parts, passed as arguments to the [`tool()`](/en/agent-sdk/typescript#tool) helper in TypeScript or the [`@tool`](/en/agent-sdk/python#tool) decorator in Python: + +* **Name:** a unique identifier Claude uses to call the tool. +* **Description:** what the tool does. Claude reads this to decide when to call it. +* **Input schema:** the arguments Claude must provide. In TypeScript this is always a [Zod schema](https://zod.dev/), and the handler's `args` are typed from it automatically. In Python this is a dict mapping names to types, like `{"latitude": float}`, which the SDK converts to JSON Schema for you. The Python decorator also accepts a full [JSON Schema](https://json-schema.org/understanding-json-schema/about) dict directly when you need enums, ranges, optional fields, or nested objects. +* **Handler:** the async function that runs when Claude calls the tool. It receives the validated arguments and must return an object with: + * `content` (required): an array of result blocks, each with a `type` of `"text"`, `"image"`, or `"resource"`. See [Return images and resources](#return-images-and-resources) for non-text blocks. + * `isError` (optional): set to `true` to signal a tool failure so Claude can react to it. See [Handle errors](#handle-errors). + +After defining a tool, wrap it in a server with [`createSdkMcpServer`](/en/agent-sdk/typescript#create-sdk-mcp-server) (TypeScript) or [`create_sdk_mcp_server`](/en/agent-sdk/python#create-sdk-mcp-server) (Python). The server runs in-process inside your application, not as a separate process. + +### Weather tool example + +This example defines a `get_temperature` tool and wraps it in an MCP server. It only sets up the tool; to pass it to `query` and run it, see [Call a custom tool](#call-a-custom-tool) below. + + + ```python Python theme={null} + from typing import Any + import httpx + from claude_agent_sdk import tool, create_sdk_mcp_server + + + # Define a tool: name, description, input schema, handler + @tool( + "get_temperature", + "Get the current temperature at a location", + {"latitude": float, "longitude": float}, + ) + async def get_temperature(args: dict[str, Any]) -> dict[str, Any]: + async with httpx.AsyncClient() as client: + response = await client.get( + "https://api.open-meteo.com/v1/forecast", + params={ + "latitude": args["latitude"], + "longitude": args["longitude"], + "current": "temperature_2m", + "temperature_unit": "fahrenheit", + }, + ) + data = response.json() + + # Return a content array - Claude sees this as the tool result + return { + "content": [ + { + "type": "text", + "text": f"Temperature: {data['current']['temperature_2m']}°F", + } + ] + } + + + # Wrap the tool in an in-process MCP server + weather_server = create_sdk_mcp_server( + name="weather", + version="1.0.0", + tools=[get_temperature], + ) + ``` + + ```typescript TypeScript theme={null} + import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk"; + import { z } from "zod"; + + // Define a tool: name, description, input schema, handler + const getTemperature = tool( + "get_temperature", + "Get the current temperature at a location", + { + latitude: z.number().describe("Latitude coordinate"), // .describe() adds a field description Claude sees + longitude: z.number().describe("Longitude coordinate") + }, + async (args) => { + // args is typed from the schema: { latitude: number; longitude: number } + const response = await fetch( + `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}¤t=temperature_2m&temperature_unit=fahrenheit` + ); + const data: any = await response.json(); + + // Return a content array - Claude sees this as the tool result + return { + content: [{ type: "text", text: `Temperature: ${data.current.temperature_2m}°F` }] + }; + } + ); + + // Wrap the tool in an in-process MCP server + const weatherServer = createSdkMcpServer({ + name: "weather", + version: "1.0.0", + tools: [getTemperature] + }); + ``` + + +See the [`tool()`](/en/agent-sdk/typescript#tool) TypeScript reference or the [`@tool`](/en/agent-sdk/python#tool) Python reference for full parameter details, including JSON Schema input formats and return value structure. + + + To make a parameter optional: in TypeScript, add `.default()` to the Zod field. In Python, the dict schema treats every key as required, so leave the parameter out of the schema, mention it in the description string, and read it with `args.get()` in the handler. The [`get_precipitation_chance` tool below](#add-more-tools) shows both patterns. + + +### Call a custom tool + +Pass the MCP server you created to `query` via the `mcpServers` option. The key in `mcpServers` becomes the `{server_name}` segment in each tool's fully qualified name: `mcp__{server_name}__{tool_name}`. List that name in `allowedTools` so the tool runs without a permission prompt. + +These snippets reuse the `weatherServer` from the [example above](#weather-tool-example) to ask Claude what the weather is in a specific location. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + + async def main(): + options = ClaudeAgentOptions( + mcp_servers={"weather": weather_server}, + allowed_tools=["mcp__weather__get_temperature"], + ) + + async for message in query( + prompt="What's the temperature in San Francisco?", + options=options, + ): + # ResultMessage is the final message after all tool calls complete + if isinstance(message, ResultMessage) and message.subtype == "success": + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "What's the temperature in San Francisco?", + options: { + mcpServers: { weather: weatherServer }, + allowedTools: ["mcp__weather__get_temperature"] + } + })) { + // "result" is the final message after all tool calls complete + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } + } + ``` + + +### Add more tools + +A server holds as many tools as you list in its `tools` array. With more than one tool on a server, you can list each one in `allowedTools` individually or use the wildcard `mcp__weather__*` to cover every tool the server exposes. + +The example below adds a second tool, `get_precipitation_chance`, to the `weatherServer` from the [weather tool example](#weather-tool-example) and rebuilds it with both tools in the array. + + + ```python Python theme={null} + # Define a second tool for the same server + @tool( + "get_precipitation_chance", + "Get the hourly precipitation probability for a location. " + "Optionally pass 'hours' (1-24) to control how many hours to return.", + {"latitude": float, "longitude": float}, + ) + async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]: + # 'hours' isn't in the schema - read it with .get() to make it optional + hours = args.get("hours", 12) + async with httpx.AsyncClient() as client: + response = await client.get( + "https://api.open-meteo.com/v1/forecast", + params={ + "latitude": args["latitude"], + "longitude": args["longitude"], + "hourly": "precipitation_probability", + "forecast_days": 1, + }, + ) + data = response.json() + chances = data["hourly"]["precipitation_probability"][:hours] + + return { + "content": [ + { + "type": "text", + "text": f"Next {hours} hours: {'%, '.join(map(str, chances))}%", + } + ] + } + + + # Rebuild the server with both tools in the array + weather_server = create_sdk_mcp_server( + name="weather", + version="1.0.0", + tools=[get_temperature, get_precipitation_chance], + ) + ``` + + ```typescript TypeScript theme={null} + // Define a second tool for the same server + const getPrecipitationChance = tool( + "get_precipitation_chance", + "Get the hourly precipitation probability for a location", + { + latitude: z.number(), + longitude: z.number(), + hours: z + .number() + .int() + .min(1) + .max(24) + .default(12) // .default() makes the parameter optional + .describe("How many hours of forecast to return") + }, + async (args) => { + const response = await fetch( + `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&hourly=precipitation_probability&forecast_days=1` + ); + const data: any = await response.json(); + const chances = data.hourly.precipitation_probability.slice(0, args.hours); + + return { + content: [{ type: "text", text: `Next ${args.hours} hours: ${chances.join("%, ")}%` }] + }; + } + ); + + // Rebuild the server with both tools in the array + const weatherServer = createSdkMcpServer({ + name: "weather", + version: "1.0.0", + tools: [getTemperature, getPrecipitationChance] + }); + ``` + + +Every tool in this array consumes context window space on every turn. If you're defining dozens of tools, see [tool search](/en/agent-sdk/tool-search) to load them on demand instead. + +### Add tool annotations + +[Tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) are optional metadata describing how a tool behaves. Pass them as the fifth argument to `tool()` helper in TypeScript or via the `annotations` keyword argument for the `@tool` decorator in Python. All hint fields are Booleans. + +| Field | Default | Meaning | +| :---------------- | :------ | :-------------------------------------------------------------------------------------------------------------------- | +| `readOnlyHint` | `false` | Tool does not modify its environment. Controls whether the tool can be called in parallel with other read-only tools. | +| `destructiveHint` | `true` | Tool may perform destructive updates. Informational only. | +| `idempotentHint` | `false` | Repeated calls with the same arguments have no additional effect. Informational only. | +| `openWorldHint` | `true` | Tool reaches systems outside your process. Informational only. | + +Annotations are metadata, not enforcement. A tool marked `readOnlyHint: true` can still write to disk if that's what the handler does. Keep the annotation accurate to the handler. + +This example adds `readOnlyHint` to the `get_temperature` tool from the [weather tool example](#weather-tool-example). + + + ```python Python theme={null} + from claude_agent_sdk import tool, ToolAnnotations + + + @tool( + "get_temperature", + "Get the current temperature at a location", + {"latitude": float, "longitude": float}, + annotations=ToolAnnotations( + readOnlyHint=True + ), # Lets Claude batch this with other read-only calls + ) + async def get_temperature(args): + return {"content": [{"type": "text", "text": "..."}]} + ``` + + ```typescript TypeScript theme={null} + tool( + "get_temperature", + "Get the current temperature at a location", + { latitude: z.number(), longitude: z.number() }, + async (args) => ({ content: [{ type: "text", text: `...` }] }), + { annotations: { readOnlyHint: true } } // Lets Claude batch this with other read-only calls + ); + ``` + + +See `ToolAnnotations` in the [TypeScript](/en/agent-sdk/typescript#tool-annotations) or [Python](/en/agent-sdk/python#tool-annotations) reference. + +## Control tool access + +The [weather tool example](#weather-tool-example) registered a server and listed tools in `allowedTools`. This section covers how tool names are constructed and how to scope access when you have multiple tools or want to restrict built-ins. + +### Tool name format + +When MCP tools are exposed to Claude, their names follow a specific format: + +* Pattern: `mcp__{server_name}__{tool_name}` +* Example: A tool named `get_temperature` in server `weather` becomes `mcp__weather__get_temperature` + +### Configure allowed tools + +The `tools` option and the allowed/disallowed lists operate on separate layers. `tools` controls which built-in tools appear in Claude's context. Allowed and disallowed tool lists control whether calls are approved or denied once Claude attempts them. + +| Option | Layer | Effect | +| :------------------------ | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | +| `tools: ["Read", "Grep"]` | Availability | Only the listed built-ins are in Claude's context. Unlisted built-ins are removed. MCP tools are unaffected. | +| `tools: []` | Availability | All built-ins are removed. Claude can only use your MCP tools. | +| allowed tools | Permission | Listed tools run without a permission prompt. Unlisted tools remain available; calls go through the [permission flow](/en/agent-sdk/permissions). | +| disallowed tools | Permission | Every call to a listed tool is denied. The tool stays in Claude's context, so Claude may still attempt it before the call is rejected. | + +To limit which built-ins Claude can use, prefer `tools` over disallowed tools. Omitting a tool from `tools` removes it from context so Claude never attempts it; listing it in `disallowedTools` (Python: `disallowed_tools`) blocks the call but leaves the tool visible, so Claude may waste a turn trying it. See [Configure permissions](/en/agent-sdk/permissions) for the full evaluation order. + +## Handle errors + +How your handler reports errors determines whether the agent loop continues or stops: + +| What happens | Result | +| :--------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | +| Handler throws an uncaught exception | Agent loop stops. Claude never sees the error, and the `query` call fails. | +| Handler catches the error and returns `isError: true` (TS) / `"is_error": True` (Python) | Agent loop continues. Claude sees the error as data and can retry, try a different tool, or explain the failure. | + +The example below catches two kinds of failures inside the handler instead of letting them throw. A non-200 HTTP status is caught from the response and returned as an error result. A network error or invalid JSON is caught by the surrounding `try/except` (Python) or `try/catch` (TypeScript) and also returned as an error result. In both cases the handler returns normally and the agent loop continues. + + + ```python Python theme={null} + import json + import httpx + from typing import Any + + + @tool( + "fetch_data", + "Fetch data from an API", + {"endpoint": str}, # Simple schema + ) + async def fetch_data(args: dict[str, Any]) -> dict[str, Any]: + try: + async with httpx.AsyncClient() as client: + response = await client.get(args["endpoint"]) + if response.status_code != 200: + # Return the failure as a tool result so Claude can react to it. + # is_error marks this as a failed call rather than odd-looking data. + return { + "content": [ + { + "type": "text", + "text": f"API error: {response.status_code} {response.reason_phrase}", + } + ], + "is_error": True, + } + + data = response.json() + return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]} + except Exception as e: + # Catching here keeps the agent loop alive. An uncaught exception + # would end the whole query() call. + return { + "content": [{"type": "text", "text": f"Failed to fetch data: {str(e)}"}], + "is_error": True, + } + ``` + + ```typescript TypeScript theme={null} + tool( + "fetch_data", + "Fetch data from an API", + { + endpoint: z.string().url().describe("API endpoint URL") + }, + async (args) => { + try { + const response = await fetch(args.endpoint); + + if (!response.ok) { + // Return the failure as a tool result so Claude can react to it. + // isError marks this as a failed call rather than odd-looking data. + return { + content: [ + { + type: "text", + text: `API error: ${response.status} ${response.statusText}` + } + ], + isError: true + }; + } + + const data = await response.json(); + return { + content: [ + { + type: "text", + text: JSON.stringify(data, null, 2) + } + ] + }; + } catch (error) { + // Catching here keeps the agent loop alive. An uncaught throw + // would end the whole query() call. + return { + content: [ + { + type: "text", + text: `Failed to fetch data: ${error instanceof Error ? error.message : String(error)}` + } + ], + isError: true + }; + } + } + ); + ``` + + +## Return images and resources + +The `content` array in a tool result accepts `text`, `image`, and `resource` blocks. You can mix them in the same response. + +### Images + +An image block carries the image bytes inline, encoded as base64. There is no URL field. To return an image that lives at a URL, fetch it in the handler, read the response bytes, and base64-encode them before returning. The result is processed as visual input. + +| Field | Type | Notes | +| :--------- | :-------- | :------------------------------------------------------------------------- | +| `type` | `"image"` | | +| `data` | `string` | Base64-encoded bytes. Raw base64 only, no `data:image/...;base64,` prefix | +| `mimeType` | `string` | Required. For example `image/png`, `image/jpeg`, `image/webp`, `image/gif` | + + + ```python Python theme={null} + import base64 + import httpx + + + # Define a tool that fetches an image from a URL and returns it to Claude + @tool("fetch_image", "Fetch an image from a URL and return it to Claude", {"url": str}) + async def fetch_image(args): + async with httpx.AsyncClient() as client: # Fetch the image bytes + response = await client.get(args["url"]) + + return { + "content": [ + { + "type": "image", + "data": base64.b64encode(response.content).decode( + "ascii" + ), # Base64-encode the raw bytes + "mimeType": response.headers.get( + "content-type", "image/png" + ), # Read MIME type from the response + } + ] + } + ``` + + ```typescript TypeScript theme={null} + tool( + "fetch_image", + "Fetch an image from a URL and return it to Claude", + { + url: z.string().url() + }, + async (args) => { + const response = await fetch(args.url); // Fetch the image bytes + const buffer = Buffer.from(await response.arrayBuffer()); // Read into a Buffer for base64 encoding + const mimeType = response.headers.get("content-type") ?? "image/png"; + + return { + content: [ + { + type: "image", + data: buffer.toString("base64"), // Base64-encode the raw bytes + mimeType + } + ] + }; + } + ); + ``` + + +### Resources + +A resource block embeds a piece of content identified by a URI. The URI is a label for Claude to reference; the actual content rides in the block's `text` or `blob` field. Use this when your tool produces something that makes sense to address by name later, such as a generated file or a record from an external system. + +| Field | Type | Notes | +| :------------------ | :----------- | :---------------------------------------------------------- | +| `type` | `"resource"` | | +| `resource.uri` | `string` | Identifier for the content. Any URI scheme | +| `resource.text` | `string` | The content, if it's text. Provide this or `blob`, not both | +| `resource.blob` | `string` | The content base64-encoded, if it's binary | +| `resource.mimeType` | `string` | Optional | + +This example shows a resource block returned from inside a tool handler. The URI `file:///tmp/report.md` is a label that Claude can reference later; the SDK does not read from that path. + + + ```typescript TypeScript theme={null} + return { + content: [ + { + type: "resource", + resource: { + uri: "file:///tmp/report.md", // Label for Claude to reference, not a path the SDK reads + mimeType: "text/markdown", + text: "# Report\n..." // The actual content, inline + } + } + ] + }; + ``` + + ```python Python theme={null} + return { + "content": [ + { + "type": "resource", + "resource": { + "uri": "file:///tmp/report.md", # Label for Claude to reference, not a path the SDK reads + "mimeType": "text/markdown", + "text": "# Report\n...", # The actual content, inline + }, + } + ] + } + ``` + + +These block shapes come from the MCP `CallToolResult` type. See the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-result) for the full definition. + +## Example: unit converter + +This tool converts values between units of length, temperature, and weight. A user can ask "convert 100 kilometers to miles" or "what is 72°F in Celsius," and Claude picks the right unit type and units from the request. + +It demonstrates two patterns: + +* **Enum schemas:** `unit_type` is constrained to a fixed set of values. In TypeScript, use `z.enum()`. In Python, the dict schema doesn't support enums, so the full JSON Schema dict is required. +* **Unsupported input handling:** when a conversion pair isn't found, the handler returns `isError: true` so Claude can tell the user what went wrong rather than treating a failure as a normal result. + + + ```python Python theme={null} + from typing import Any + from claude_agent_sdk import tool, create_sdk_mcp_server + + + # z.enum() in TypeScript becomes an "enum" constraint in JSON Schema. + # The dict schema has no equivalent, so full JSON Schema is required. + @tool( + "convert_units", + "Convert a value from one unit to another", + { + "type": "object", + "properties": { + "unit_type": { + "type": "string", + "enum": ["length", "temperature", "weight"], + "description": "Category of unit", + }, + "from_unit": { + "type": "string", + "description": "Unit to convert from, e.g. kilometers, fahrenheit, pounds", + }, + "to_unit": {"type": "string", "description": "Unit to convert to"}, + "value": {"type": "number", "description": "Value to convert"}, + }, + "required": ["unit_type", "from_unit", "to_unit", "value"], + }, + ) + async def convert_units(args: dict[str, Any]) -> dict[str, Any]: + conversions = { + "length": { + "kilometers_to_miles": lambda v: v * 0.621371, + "miles_to_kilometers": lambda v: v * 1.60934, + "meters_to_feet": lambda v: v * 3.28084, + "feet_to_meters": lambda v: v * 0.3048, + }, + "temperature": { + "celsius_to_fahrenheit": lambda v: (v * 9) / 5 + 32, + "fahrenheit_to_celsius": lambda v: (v - 32) * 5 / 9, + "celsius_to_kelvin": lambda v: v + 273.15, + "kelvin_to_celsius": lambda v: v - 273.15, + }, + "weight": { + "kilograms_to_pounds": lambda v: v * 2.20462, + "pounds_to_kilograms": lambda v: v * 0.453592, + "grams_to_ounces": lambda v: v * 0.035274, + "ounces_to_grams": lambda v: v * 28.3495, + }, + } + + key = f"{args['from_unit']}_to_{args['to_unit']}" + fn = conversions.get(args["unit_type"], {}).get(key) + + if not fn: + return { + "content": [ + { + "type": "text", + "text": f"Unsupported conversion: {args['from_unit']} to {args['to_unit']}", + } + ], + "is_error": True, + } + + result = fn(args["value"]) + return { + "content": [ + { + "type": "text", + "text": f"{args['value']} {args['from_unit']} = {result:.4f} {args['to_unit']}", + } + ] + } + + + converter_server = create_sdk_mcp_server( + name="converter", + version="1.0.0", + tools=[convert_units], + ) + ``` + + ```typescript TypeScript theme={null} + import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk"; + import { z } from "zod"; + + const convert = tool( + "convert_units", + "Convert a value from one unit to another", + { + unit_type: z.enum(["length", "temperature", "weight"]).describe("Category of unit"), + from_unit: z + .string() + .describe("Unit to convert from, e.g. kilometers, fahrenheit, pounds"), + to_unit: z.string().describe("Unit to convert to"), + value: z.number().describe("Value to convert") + }, + async (args) => { + type Conversions = Record number>>; + + const conversions: Conversions = { + length: { + kilometers_to_miles: (v) => v * 0.621371, + miles_to_kilometers: (v) => v * 1.60934, + meters_to_feet: (v) => v * 3.28084, + feet_to_meters: (v) => v * 0.3048 + }, + temperature: { + celsius_to_fahrenheit: (v) => (v * 9) / 5 + 32, + fahrenheit_to_celsius: (v) => ((v - 32) * 5) / 9, + celsius_to_kelvin: (v) => v + 273.15, + kelvin_to_celsius: (v) => v - 273.15 + }, + weight: { + kilograms_to_pounds: (v) => v * 2.20462, + pounds_to_kilograms: (v) => v * 0.453592, + grams_to_ounces: (v) => v * 0.035274, + ounces_to_grams: (v) => v * 28.3495 + } + }; + + const key = `${args.from_unit}_to_${args.to_unit}`; + const fn = conversions[args.unit_type]?.[key]; + + if (!fn) { + return { + content: [ + { + type: "text", + text: `Unsupported conversion: ${args.from_unit} to ${args.to_unit}` + } + ], + isError: true + }; + } + + const result = fn(args.value); + return { + content: [ + { + type: "text", + text: `${args.value} ${args.from_unit} = ${result.toFixed(4)} ${args.to_unit}` + } + ] + }; + } + ); + + const converterServer = createSdkMcpServer({ + name: "converter", + version: "1.0.0", + tools: [convert] + }); + ``` + + +Once the server is defined, pass it to `query` the same way as the weather example. This example sends three different prompts in a loop to show the same tool handling different unit types. For each response, it inspects `AssistantMessage` objects (which contain the tool calls Claude made during that turn) and prints each `ToolUseBlock` before printing the final `ResultMessage` text. This lets you see when Claude is using the tool versus answering from its own knowledge. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import ( + query, + ClaudeAgentOptions, + ResultMessage, + AssistantMessage, + ToolUseBlock, + ) + + + async def main(): + options = ClaudeAgentOptions( + mcp_servers={"converter": converter_server}, + allowed_tools=["mcp__converter__convert_units"], + ) + + prompts = [ + "Convert 100 kilometers to miles.", + "What is 72°F in Celsius?", + "How many pounds is 5 kilograms?", + ] + + for prompt in prompts: + async for message in query(prompt=prompt, options=options): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, ToolUseBlock): + print(f"[tool call] {block.name}({block.input})") + elif isinstance(message, ResultMessage) and message.subtype == "success": + print(f"Q: {prompt}\nA: {message.result}\n") + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + const prompts = [ + "Convert 100 kilometers to miles.", + "What is 72°F in Celsius?", + "How many pounds is 5 kilograms?" + ]; + + for (const prompt of prompts) { + for await (const message of query({ + prompt, + options: { + mcpServers: { converter: converterServer }, + allowedTools: ["mcp__converter__convert_units"] + } + })) { + if (message.type === "assistant") { + for (const block of message.message.content) { + if (block.type === "tool_use") { + console.log(`[tool call] ${block.name}`, block.input); + } + } + } else if (message.type === "result" && message.subtype === "success") { + console.log(`Q: ${prompt}\nA: ${message.result}\n`); + } + } + } + ``` + + +## Next steps + +Custom tools wrap async functions in a standard interface. You can mix the patterns on this page in the same server: a single server can hold a database tool, an API gateway tool, and an image renderer alongside each other. + +From here: + +* If your server grows to dozens of tools, see [tool search](/en/agent-sdk/tool-search) to defer loading them until Claude needs them. +* To connect to external MCP servers (filesystem, GitHub, Slack) instead of building your own, see [Connect MCP servers](/en/agent-sdk/mcp). +* To control which tools run automatically versus requiring approval, see [Configure permissions](/en/agent-sdk/permissions). + +## Related documentation + +* [TypeScript SDK Reference](/en/agent-sdk/typescript) +* [Python SDK Reference](/en/agent-sdk/python) +* [MCP Documentation](https://modelcontextprotocol.io) +* [SDK Overview](/en/agent-sdk/overview) diff --git a/content/en/docs/claude-code/agent-sdk/file-checkpointing.md b/content/en/docs/claude-code/agent-sdk/file-checkpointing.md new file mode 100644 index 000000000..146ae3662 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/file-checkpointing.md @@ -0,0 +1,770 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Rewind file changes with checkpointing + +> Track file changes during agent sessions and restore files to any previous state + +File checkpointing tracks file modifications made through the Write, Edit, and NotebookEdit tools during an agent session, allowing you to rewind files to any previous state. Want to try it out? Jump to the [interactive example](#try-it-out). + +With checkpointing, you can: + +* **Undo unwanted changes** by restoring files to a known good state +* **Explore alternatives** by restoring to a checkpoint and trying a different approach +* **Recover from errors** when the agent makes incorrect modifications + + + Only changes made through the Write, Edit, and NotebookEdit tools are tracked. Changes made through Bash commands (like `echo > file.txt` or `sed -i`) are not captured by the checkpoint system. + + +## How checkpointing works + +When you enable file checkpointing, the SDK creates backups of files before modifying them through the Write, Edit, or NotebookEdit tools. User messages in the response stream include a checkpoint UUID that you can use as a restore point. + +Checkpoint works with these built-in tools that the agent uses to modify files: + +| Tool | Description | +| ------------ | ------------------------------------------------------------------ | +| Write | Creates a new file or overwrites an existing file with new content | +| Edit | Makes targeted edits to specific parts of an existing file | +| NotebookEdit | Modifies cells in Jupyter notebooks (`.ipynb` files) | + + + File rewinding restores files on disk to a previous state. It does not rewind the conversation itself. The conversation history and context remain intact after calling `rewindFiles()` (TypeScript) or `rewind_files()` (Python). + + +The checkpoint system tracks: + +* Files created during the session +* Files modified during the session +* The original content of modified files + +When you rewind to a checkpoint, created files are deleted and modified files are restored to their content at that point. + +## Implement checkpointing + +To use file checkpointing, enable it in your options, capture checkpoint UUIDs from the response stream, then call `rewindFiles()` (TypeScript) or `rewind_files()` (Python) when you need to restore. + +The following example shows the complete flow: enable checkpointing, capture the checkpoint UUID and session ID from the response stream, then resume the session later to rewind files. Each step is explained in detail below. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import ( + ClaudeSDKClient, + ClaudeAgentOptions, + UserMessage, + ResultMessage, + ) + + + async def main(): + # Step 1: Enable checkpointing + options = ClaudeAgentOptions( + enable_file_checkpointing=True, + permission_mode="acceptEdits", # Auto-accept file edits without prompting + extra_args={ + "replay-user-messages": None + }, # Required to receive checkpoint UUIDs in the response stream + ) + + checkpoint_id = None + session_id = None + + # Run the query and capture checkpoint UUID and session ID + async with ClaudeSDKClient(options) as client: + await client.query("Refactor the authentication module") + + # Step 2: Capture checkpoint UUID from the first user message + async for message in client.receive_response(): + if isinstance(message, UserMessage) and message.uuid and not checkpoint_id: + checkpoint_id = message.uuid + if isinstance(message, ResultMessage) and not session_id: + session_id = message.session_id + + # Step 3: Later, rewind by resuming the session with an empty prompt + if checkpoint_id and session_id: + async with ClaudeSDKClient( + ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id) + ) as client: + await client.query("") # Empty prompt to open the connection + async for message in client.receive_response(): + await client.rewind_files(checkpoint_id) + break + print(f"Rewound to checkpoint: {checkpoint_id}") + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + async function main() { + // Step 1: Enable checkpointing + const opts = { + enableFileCheckpointing: true, + permissionMode: "acceptEdits" as const, // Auto-accept file edits without prompting + extraArgs: { "replay-user-messages": null } // Required to receive checkpoint UUIDs in the response stream + }; + + const response = query({ + prompt: "Refactor the authentication module", + options: opts + }); + + let checkpointId: string | undefined; + let sessionId: string | undefined; + + // Step 2: Capture checkpoint UUID from the first user message + for await (const message of response) { + if (message.type === "user" && message.uuid && !checkpointId) { + checkpointId = message.uuid; + } + if ("session_id" in message && !sessionId) { + sessionId = message.session_id; + } + } + + // Step 3: Later, rewind by resuming the session with an empty prompt + if (checkpointId && sessionId) { + const rewindQuery = query({ + prompt: "", // Empty prompt to open the connection + options: { ...opts, resume: sessionId } + }); + + for await (const msg of rewindQuery) { + await rewindQuery.rewindFiles(checkpointId); + break; + } + console.log(`Rewound to checkpoint: ${checkpointId}`); + } + } + + main(); + ``` + + + + + Configure your SDK options to enable checkpointing and receive checkpoint UUIDs: + + | Option | Python | TypeScript | Description | + | ------------------------ | ------------------------------------------- | --------------------------------------------- | ------------------------------------------------ | + | Enable checkpointing | `enable_file_checkpointing=True` | `enableFileCheckpointing: true` | Tracks file changes for rewinding | + | Receive checkpoint UUIDs | `extra_args={"replay-user-messages": None}` | `extraArgs: { 'replay-user-messages': null }` | Required to get user message UUIDs in the stream | + + + ```python Python theme={null} + options = ClaudeAgentOptions( + enable_file_checkpointing=True, + permission_mode="acceptEdits", + extra_args={"replay-user-messages": None}, + ) + + async with ClaudeSDKClient(options) as client: + await client.query("Refactor the authentication module") + ``` + + ```typescript TypeScript theme={null} + const response = query({ + prompt: "Refactor the authentication module", + options: { + enableFileCheckpointing: true, + permissionMode: "acceptEdits" as const, + extraArgs: { "replay-user-messages": null } + } + }); + ``` + + + + + With the `replay-user-messages` option set (shown above), each user message in the response stream has a UUID that serves as a checkpoint. + + For most use cases, capture the first user message UUID (`message.uuid`); rewinding to it restores all files to their original state. To store multiple checkpoints and rewind to intermediate states, see [Multiple restore points](#multiple-restore-points). + + Capturing the session ID (`message.session_id`) is optional; you only need it if you want to rewind later, after the stream completes. If you're calling `rewindFiles()` immediately while still processing messages (as the example in [Checkpoint before risky operations](#checkpoint-before-risky-operations) does), you can skip capturing the session ID. + + + ```python Python theme={null} + checkpoint_id = None + session_id = None + + async for message in client.receive_response(): + # Update checkpoint on each user message (keeps the latest) + if isinstance(message, UserMessage) and message.uuid: + checkpoint_id = message.uuid + # Capture session ID from the result message + if isinstance(message, ResultMessage): + session_id = message.session_id + ``` + + ```typescript TypeScript theme={null} + let checkpointId: string | undefined; + let sessionId: string | undefined; + + for await (const message of response) { + // Update checkpoint on each user message (keeps the latest) + if (message.type === "user" && message.uuid) { + checkpointId = message.uuid; + } + // Capture session ID from any message that has it + if ("session_id" in message) { + sessionId = message.session_id; + } + } + ``` + + + + + To rewind after the stream completes, resume the session with an empty prompt and call `rewind_files()` (Python) or `rewindFiles()` (TypeScript) with your checkpoint UUID. You can also rewind during the stream; see [Checkpoint before risky operations](#checkpoint-before-risky-operations) for that pattern. + + + ```python Python theme={null} + async with ClaudeSDKClient( + ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id) + ) as client: + await client.query("") # Empty prompt to open the connection + async for message in client.receive_response(): + await client.rewind_files(checkpoint_id) + break + ``` + + ```typescript TypeScript theme={null} + const rewindQuery = query({ + prompt: "", // Empty prompt to open the connection + options: { ...opts, resume: sessionId } + }); + + for await (const msg of rewindQuery) { + await rewindQuery.rewindFiles(checkpointId); + break; + } + ``` + + + If you capture the session ID and checkpoint ID, you can also rewind from the CLI: + + ```bash theme={null} + claude -p --resume --rewind-files + ``` + + + +## Common patterns + +These patterns show different ways to capture and use checkpoint UUIDs depending on your use case. + +### Checkpoint before risky operations + +This pattern keeps only the most recent checkpoint UUID, updating it before each agent turn. If something goes wrong during processing, you can immediately rewind to the last safe state and break out of the loop. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage + + + async def main(): + options = ClaudeAgentOptions( + enable_file_checkpointing=True, + permission_mode="acceptEdits", + extra_args={"replay-user-messages": None}, + ) + + safe_checkpoint = None + + async with ClaudeSDKClient(options) as client: + await client.query("Refactor the authentication module") + + async for message in client.receive_response(): + # Update checkpoint before each agent turn starts + # This overwrites the previous checkpoint. Only keep the latest + if isinstance(message, UserMessage) and message.uuid: + safe_checkpoint = message.uuid + + # Decide when to revert based on your own logic + # For example: error detection, validation failure, or user input + if your_revert_condition and safe_checkpoint: + await client.rewind_files(safe_checkpoint) + # Exit the loop after rewinding, files are restored + break + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + async function main() { + const response = query({ + prompt: "Refactor the authentication module", + options: { + enableFileCheckpointing: true, + permissionMode: "acceptEdits" as const, + extraArgs: { "replay-user-messages": null } + } + }); + + let safeCheckpoint: string | undefined; + + for await (const message of response) { + // Update checkpoint before each agent turn starts + // This overwrites the previous checkpoint. Only keep the latest + if (message.type === "user" && message.uuid) { + safeCheckpoint = message.uuid; + } + + // Decide when to revert based on your own logic + // For example: error detection, validation failure, or user input + if (yourRevertCondition && safeCheckpoint) { + await response.rewindFiles(safeCheckpoint); + // Exit the loop after rewinding, files are restored + break; + } + } + } + + main(); + ``` + + +### Multiple restore points + +If Claude makes changes across multiple turns, you might want to rewind to a specific point rather than all the way back. For example, if Claude refactors a file in turn one and adds tests in turn two, you might want to keep the refactor but undo the tests. + +This pattern stores all checkpoint UUIDs in an array with metadata. After the session completes, you can rewind to any previous checkpoint: + + + ```python Python theme={null} + import asyncio + from dataclasses import dataclass + from datetime import datetime + from claude_agent_sdk import ( + ClaudeSDKClient, + ClaudeAgentOptions, + UserMessage, + ResultMessage, + ) + + + # Store checkpoint metadata for better tracking + @dataclass + class Checkpoint: + id: str + description: str + timestamp: datetime + + + async def main(): + options = ClaudeAgentOptions( + enable_file_checkpointing=True, + permission_mode="acceptEdits", + extra_args={"replay-user-messages": None}, + ) + + checkpoints = [] + session_id = None + + async with ClaudeSDKClient(options) as client: + await client.query("Refactor the authentication module") + + async for message in client.receive_response(): + if isinstance(message, UserMessage) and message.uuid: + checkpoints.append( + Checkpoint( + id=message.uuid, + description=f"After turn {len(checkpoints) + 1}", + timestamp=datetime.now(), + ) + ) + if isinstance(message, ResultMessage) and not session_id: + session_id = message.session_id + + # Later: rewind to any checkpoint by resuming the session + if checkpoints and session_id: + target = checkpoints[0] # Pick any checkpoint + async with ClaudeSDKClient( + ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id) + ) as client: + await client.query("") # Empty prompt to open the connection + async for message in client.receive_response(): + await client.rewind_files(target.id) + break + print(f"Rewound to: {target.description}") + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Store checkpoint metadata for better tracking + interface Checkpoint { + id: string; + description: string; + timestamp: Date; + } + + async function main() { + const opts = { + enableFileCheckpointing: true, + permissionMode: "acceptEdits" as const, + extraArgs: { "replay-user-messages": null } + }; + + const response = query({ + prompt: "Refactor the authentication module", + options: opts + }); + + const checkpoints: Checkpoint[] = []; + let sessionId: string | undefined; + + for await (const message of response) { + if (message.type === "user" && message.uuid) { + checkpoints.push({ + id: message.uuid, + description: `After turn ${checkpoints.length + 1}`, + timestamp: new Date() + }); + } + if ("session_id" in message && !sessionId) { + sessionId = message.session_id; + } + } + + // Later: rewind to any checkpoint by resuming the session + if (checkpoints.length > 0 && sessionId) { + const target = checkpoints[0]; // Pick any checkpoint + const rewindQuery = query({ + prompt: "", // Empty prompt to open the connection + options: { ...opts, resume: sessionId } + }); + + for await (const msg of rewindQuery) { + await rewindQuery.rewindFiles(target.id); + break; + } + console.log(`Rewound to: ${target.description}`); + } + } + + main(); + ``` + + +## Try it out + +This complete example creates a small utility file, has the agent add documentation comments, shows you the changes, then asks if you want to rewind. + +Before you begin, make sure you have the [Claude Agent SDK installed](/en/agent-sdk/quickstart). + + + + Create a new file called `utils.py` (Python) or `utils.ts` (TypeScript) and paste the following code: + + + ```python utils.py theme={null} + def add(a, b): + return a + b + + + def subtract(a, b): + return a - b + + + def multiply(a, b): + return a * b + + + def divide(a, b): + if b == 0: + raise ValueError("Cannot divide by zero") + return a / b + ``` + + ```typescript utils.ts theme={null} + export function add(a: number, b: number): number { + return a + b; + } + + export function subtract(a: number, b: number): number { + return a - b; + } + + export function multiply(a: number, b: number): number { + return a * b; + } + + export function divide(a: number, b: number): number { + if (b === 0) { + throw new Error("Cannot divide by zero"); + } + return a / b; + } + ``` + + + + + Create a new file called `try_checkpointing.py` (Python) or `try_checkpointing.ts` (TypeScript) in the same directory as your utility file, and paste the following code. + + This script asks Claude to add doc comments to your utility file, then gives you the option to rewind and restore the original. + + + ```python try_checkpointing.py theme={null} + import asyncio + from claude_agent_sdk import ( + ClaudeSDKClient, + ClaudeAgentOptions, + UserMessage, + ResultMessage, + ) + + + async def main(): + # Configure the SDK with checkpointing enabled + # - enable_file_checkpointing: Track file changes for rewinding + # - permission_mode: Auto-accept file edits without prompting + # - extra_args: Required to receive user message UUIDs in the stream + options = ClaudeAgentOptions( + enable_file_checkpointing=True, + permission_mode="acceptEdits", + extra_args={"replay-user-messages": None}, + ) + + checkpoint_id = None # Store the user message UUID for rewinding + session_id = None # Store the session ID for resuming + + print("Running agent to add doc comments to utils.py...\n") + + # Run the agent and capture checkpoint data from the response stream + async with ClaudeSDKClient(options) as client: + await client.query("Add doc comments to utils.py") + + async for message in client.receive_response(): + # Capture the first user message UUID - this is our restore point + if isinstance(message, UserMessage) and message.uuid and not checkpoint_id: + checkpoint_id = message.uuid + # Capture the session ID so we can resume later + if isinstance(message, ResultMessage): + session_id = message.session_id + + print("Done! Open utils.py to see the added doc comments.\n") + + # Ask the user if they want to rewind the changes + if checkpoint_id and session_id: + response = input("Rewind to remove the doc comments? (y/n): ") + + if response.lower() == "y": + # Resume the session with an empty prompt, then rewind + async with ClaudeSDKClient( + ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id) + ) as client: + await client.query("") # Empty prompt opens the connection + async for message in client.receive_response(): + await client.rewind_files(checkpoint_id) # Restore files + break + + print( + "\n✓ File restored! Open utils.py to verify the doc comments are gone." + ) + else: + print("\nKept the modified file.") + + + asyncio.run(main()) + ``` + + ```typescript try_checkpointing.ts theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + import * as readline from "readline"; + + async function main() { + // Configure the SDK with checkpointing enabled + // - enableFileCheckpointing: Track file changes for rewinding + // - permissionMode: Auto-accept file edits without prompting + // - extraArgs: Required to receive user message UUIDs in the stream + const opts = { + enableFileCheckpointing: true, + permissionMode: "acceptEdits" as const, + extraArgs: { "replay-user-messages": null } + }; + + let sessionId: string | undefined; // Store the session ID for resuming + let checkpointId: string | undefined; // Store the user message UUID for rewinding + + console.log("Running agent to add doc comments to utils.ts...\n"); + + // Run the agent and capture checkpoint data from the response stream + const response = query({ + prompt: "Add doc comments to utils.ts", + options: opts + }); + + for await (const message of response) { + // Capture the first user message UUID - this is our restore point + if (message.type === "user" && message.uuid && !checkpointId) { + checkpointId = message.uuid; + } + // Capture the session ID so we can resume later + if ("session_id" in message) { + sessionId = message.session_id; + } + } + + console.log("Done! Open utils.ts to see the added doc comments.\n"); + + // Ask the user if they want to rewind the changes + if (checkpointId && sessionId) { + const rl = readline.createInterface({ + input: process.stdin, + output: process.stdout + }); + + const answer = await new Promise((resolve) => { + rl.question("Rewind to remove the doc comments? (y/n): ", resolve); + }); + rl.close(); + + if (answer.toLowerCase() === "y") { + // Resume the session with an empty prompt, then rewind + const rewindQuery = query({ + prompt: "", // Empty prompt opens the connection + options: { ...opts, resume: sessionId } + }); + + for await (const msg of rewindQuery) { + await rewindQuery.rewindFiles(checkpointId); // Restore files + break; + } + + console.log("\n✓ File restored! Open utils.ts to verify the doc comments are gone."); + } else { + console.log("\nKept the modified file."); + } + } + } + + main(); + ``` + + + This example demonstrates the complete checkpointing workflow: + + 1. **Enable checkpointing**: configure the SDK with `enable_file_checkpointing=True` and `permission_mode="acceptEdits"` to auto-approve file edits + 2. **Capture checkpoint data**: as the agent runs, store the first user message UUID (your restore point) and the session ID + 3. **Prompt for rewind**: after the agent finishes, check your utility file to see the doc comments, then decide if you want to undo the changes + 4. **Resume and rewind**: if yes, resume the session with an empty prompt and call `rewind_files()` to restore the original file + + + + Run the script from the same directory as your utility file. + + + Open your utility file (`utils.py` or `utils.ts`) in your IDE or editor before running the script. You'll see the file update in real-time as the agent adds doc comments, then revert back to the original when you choose to rewind. + + + + + ```bash theme={null} + python try_checkpointing.py + ``` + + + + ```bash theme={null} + npx tsx try_checkpointing.ts + ``` + + + + You'll see the agent add doc comments, then a prompt asking if you want to rewind. If you choose yes, the file is restored to its original state. + + + +## Limitations + +File checkpointing has the following limitations: + +| Limitation | Description | +| ---------------------------------- | -------------------------------------------------------------------- | +| Write/Edit/NotebookEdit tools only | Changes made through Bash commands are not tracked | +| Same session | Checkpoints are tied to the session that created them | +| File content only | Creating, moving, or deleting directories is not undone by rewinding | +| Local files | Remote or network files are not tracked | + +## Troubleshooting + +### Checkpointing options not recognized + +If `enableFileCheckpointing` or `rewindFiles()` isn't available, you may be on an older SDK version. + +**Solution**: Update to the latest SDK version: + +* **Python**: `pip install --upgrade claude-agent-sdk` +* **TypeScript**: `npm install @anthropic-ai/claude-agent-sdk@latest` + +### User messages don't have UUIDs + +If `message.uuid` is `undefined` or missing, you're not receiving checkpoint UUIDs. + +**Cause**: The `replay-user-messages` option isn't set. + +**Solution**: Add `extra_args={"replay-user-messages": None}` (Python) or `extraArgs: { 'replay-user-messages': null }` (TypeScript) to your options. + +### "No file checkpoint found for message" error + +This error occurs when the checkpoint data doesn't exist for the specified user message UUID. + +**Common causes**: + +* File checkpointing was not enabled on the original session (`enable_file_checkpointing` or `enableFileCheckpointing` was not set to `true`) +* The session wasn't properly completed before attempting to resume and rewind + +**Solution**: Ensure `enable_file_checkpointing=True` (Python) or `enableFileCheckpointing: true` (TypeScript) was set on the original session, then use the pattern shown in the examples: capture the first user message UUID, complete the session fully, then resume with an empty prompt and call `rewindFiles()` once. + +### "ProcessTransport is not ready for writing" error + +This error occurs when you call `rewindFiles()` or `rewind_files()` after you've finished iterating through the response. The connection to the CLI process closes when the loop completes. + +**Solution**: Resume the session with an empty prompt, then call rewind on the new query: + + + ```python Python theme={null} + # Resume session with empty prompt, then rewind + async with ClaudeSDKClient( + ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id) + ) as client: + await client.query("") + async for message in client.receive_response(): + await client.rewind_files(checkpoint_id) + break + ``` + + ```typescript TypeScript theme={null} + // Resume session with empty prompt, then rewind + const rewindQuery = query({ + prompt: "", + options: { ...opts, resume: sessionId } + }); + + for await (const msg of rewindQuery) { + await rewindQuery.rewindFiles(checkpointId); + break; + } + ``` + + +## Next steps + +* **[Sessions](/en/agent-sdk/sessions)**: learn how to resume sessions, which is required for rewinding after the stream completes. Covers session IDs, resuming conversations, and session forking. +* **[Permissions](/en/agent-sdk/permissions)**: configure which tools Claude can use and how file modifications are approved. Useful if you want more control over when edits happen. +* **[TypeScript SDK reference](/en/agent-sdk/typescript)**: complete API reference including all options for `query()` and the `rewindFiles()` method. +* **[Python SDK reference](/en/agent-sdk/python)**: complete API reference including all options for `ClaudeAgentOptions` and the `rewind_files()` method. diff --git a/content/en/docs/claude-code/agent-sdk/hooks.md b/content/en/docs/claude-code/agent-sdk/hooks.md new file mode 100644 index 000000000..de2fc78fa --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/hooks.md @@ -0,0 +1,818 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Intercept and control agent behavior with hooks + +> Intercept and customize agent behavior at key execution points with hooks + +Hooks are callback functions that run your code in response to agent events, like a tool being called, a session starting, or execution stopping. With hooks, you can: + +* **Block dangerous operations** before they execute, like destructive shell commands or unauthorized file access +* **Log and audit** every tool call for compliance, debugging, or analytics +* **Transform inputs and outputs** to sanitize data, inject credentials, or redirect file paths +* **Require human approval** for sensitive actions like database writes or API calls +* **Track session lifecycle** to manage state, clean up resources, or send notifications + +This guide covers how hooks work, how to configure them, and provides examples for common patterns like blocking tools, modifying inputs, and forwarding notifications. + +## How hooks work + + + + Something happens during agent execution and the SDK fires an event: a tool is about to be called (`PreToolUse`), a tool returned a result (`PostToolUse`), a subagent started or stopped, the agent is idle, or execution finished. See the [full list of events](#available-hooks). + + + + The SDK checks for hooks registered for that event type. This includes callback hooks you pass in `options.hooks` and shell command hooks from settings files, but only if you explicitly load them with [`settingSources`](/en/agent-sdk/typescript#setting-source) or [`setting_sources`](/en/agent-sdk/python#setting-source). + + + + If a hook has a [`matcher`](#matchers) pattern (like `"Write|Edit"`), the SDK tests it against the event's target (for example, the tool name). Hooks without a matcher run for every event of that type. + + + + Each matching hook's [callback function](#callback-functions) receives input about what's happening: the tool name, its arguments, the session ID, and other event-specific details. + + + + After performing any operations (logging, API calls, validation), your callback returns an [output object](#outputs) that tells the agent what to do: allow the operation, block it, modify the input, or inject context into the conversation. + + + +The following example puts these steps together. It registers a `PreToolUse` hook (step 1) with a `"Write|Edit"` matcher (step 3) so the callback only fires for file-writing tools. When triggered, the callback receives the tool's input (step 4), checks if the file path targets a `.env` file, and returns `permissionDecision: "deny"` to block the operation (step 5): + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import ( + AssistantMessage, + ClaudeSDKClient, + ClaudeAgentOptions, + HookMatcher, + ResultMessage, + ) + + + # Define a hook callback that receives tool call details + async def protect_env_files(input_data, tool_use_id, context): + # Extract the file path from the tool's input arguments + file_path = input_data["tool_input"].get("file_path", "") + file_name = file_path.split("/")[-1] + + # Block the operation if targeting a .env file + if file_name == ".env": + return { + "hookSpecificOutput": { + "hookEventName": input_data["hook_event_name"], + "permissionDecision": "deny", + "permissionDecisionReason": "Cannot modify .env files", + } + } + + # Return empty object to allow the operation + return {} + + + async def main(): + options = ClaudeAgentOptions( + hooks={ + # Register the hook for PreToolUse events + # The matcher filters to only Write and Edit tool calls + "PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])] + } + ) + + async with ClaudeSDKClient(options=options) as client: + await client.query("Update the database configuration") + async for message in client.receive_response(): + # Filter for assistant and result messages + if isinstance(message, (AssistantMessage, ResultMessage)): + print(message) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query, HookCallback, PreToolUseHookInput } from "@anthropic-ai/claude-agent-sdk"; + + // Define a hook callback with the HookCallback type + const protectEnvFiles: HookCallback = async (input, toolUseID, { signal }) => { + // Cast input to the specific hook type for type safety + const preInput = input as PreToolUseHookInput; + + // Cast tool_input to access its properties (typed as unknown in the SDK) + const toolInput = preInput.tool_input as Record; + const filePath = toolInput?.file_path as string; + const fileName = filePath?.split("/").pop(); + + // Block the operation if targeting a .env file + if (fileName === ".env") { + return { + hookSpecificOutput: { + hookEventName: preInput.hook_event_name, + permissionDecision: "deny", + permissionDecisionReason: "Cannot modify .env files" + } + }; + } + + // Return empty object to allow the operation + return {}; + }; + + for await (const message of query({ + prompt: "Update the database configuration", + options: { + hooks: { + // Register the hook for PreToolUse events + // The matcher filters to only Write and Edit tool calls + PreToolUse: [{ matcher: "Write|Edit", hooks: [protectEnvFiles] }] + } + } + })) { + // Filter for assistant and result messages + if (message.type === "assistant" || message.type === "result") { + console.log(message); + } + } + ``` + + +## Available hooks + +The SDK provides hooks for different stages of agent execution. Some hooks are available in both SDKs, while others are TypeScript-only. + +| Hook Event | Python SDK | TypeScript SDK | What triggers it | Example use case | +| -------------------- | ---------- | -------------- | --------------------------------------- | ----------------------------------------------- | +| `PreToolUse` | Yes | Yes | Tool call request (can block or modify) | Block dangerous shell commands | +| `PostToolUse` | Yes | Yes | Tool execution result | Log all file changes to audit trail | +| `PostToolUseFailure` | Yes | Yes | Tool execution failure | Handle or log tool errors | +| `UserPromptSubmit` | Yes | Yes | User prompt submission | Inject additional context into prompts | +| `Stop` | Yes | Yes | Agent execution stop | Save session state before exit | +| `SubagentStart` | Yes | Yes | Subagent initialization | Track parallel task spawning | +| `SubagentStop` | Yes | Yes | Subagent completion | Aggregate results from parallel tasks | +| `PreCompact` | Yes | Yes | Conversation compaction request | Archive full transcript before summarizing | +| `PermissionRequest` | Yes | Yes | Permission dialog would be displayed | Custom permission handling | +| `SessionStart` | No | Yes | Session initialization | Initialize logging and telemetry | +| `SessionEnd` | No | Yes | Session termination | Clean up temporary resources | +| `Notification` | Yes | Yes | Agent status messages | Send agent status updates to Slack or PagerDuty | +| `Setup` | No | Yes | Session setup/maintenance | Run initialization tasks | +| `TeammateIdle` | No | Yes | Teammate becomes idle | Reassign work or notify | +| `TaskCompleted` | No | Yes | Background task completes | Aggregate results from parallel tasks | +| `ConfigChange` | No | Yes | Configuration file changes | Reload settings dynamically | +| `WorktreeCreate` | No | Yes | Git worktree created | Track isolated workspaces | +| `WorktreeRemove` | No | Yes | Git worktree removed | Clean up workspace resources | + +## Configure hooks + +To configure a hook, pass it in the `hooks` field of your agent options (`ClaudeAgentOptions` in Python, the `options` object in TypeScript): + + + ```python Python theme={null} + options = ClaudeAgentOptions( + hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[my_callback])]} + ) + + async with ClaudeSDKClient(options=options) as client: + await client.query("Your prompt") + async for message in client.receive_response(): + print(message) + ``` + + ```typescript TypeScript theme={null} + for await (const message of query({ + prompt: "Your prompt", + options: { + hooks: { + PreToolUse: [{ matcher: "Bash", hooks: [myCallback] }] + } + } + })) { + console.log(message); + } + ``` + + +The `hooks` option is a dictionary (Python) or object (TypeScript) where: + +* **Keys** are [hook event names](#available-hooks) (e.g., `'PreToolUse'`, `'PostToolUse'`, `'Stop'`) +* **Values** are arrays of [matchers](#matchers), each containing an optional filter pattern and your [callback functions](#callback-functions) + +### Matchers + +Use matchers to filter when your callbacks fire. The `matcher` field is a regex string that matches against a different value depending on the hook event type. For example, tool-based hooks match against the tool name, while `Notification` hooks match against the notification type. See the [Claude Code hooks reference](/en/hooks#matcher-patterns) for the full list of matcher values for each event type. + +| Option | Type | Default | Description | +| --------- | ---------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `matcher` | `string` | `undefined` | Regex pattern matched against the event's filter field. For tool hooks, this is the tool name. Built-in tools include `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`, `Agent`, and others (see [Tool Input Types](/en/agent-sdk/typescript#tool-input-types) for the full list). MCP tools use the pattern `mcp____`. | +| `hooks` | `HookCallback[]` | - | Required. Array of callback functions to execute when the pattern matches | +| `timeout` | `number` | `60` | Timeout in seconds | + +Use the `matcher` pattern to target specific tools whenever possible. A matcher with `'Bash'` only runs for Bash commands, while omitting the pattern runs your callbacks for every occurrence of the event. Note that for tool-based hooks, matchers only filter by **tool name**, not by file paths or other arguments. To filter by file path, check `tool_input.file_path` inside your callback. + + + **Discovering tool names:** See [Tool Input Types](/en/agent-sdk/typescript#tool-input-types) for the full list of built-in tool names, or add a hook without a matcher to log all tool calls your session makes. + + **MCP tool naming:** MCP tools always start with `mcp__` followed by the server name and action: `mcp____`. For example, if you configure a server named `playwright`, its tools will be named `mcp__playwright__browser_screenshot`, `mcp__playwright__browser_click`, etc. The server name comes from the key you use in the `mcpServers` configuration. + + +### Callback functions + +#### Inputs + +Every hook callback receives three arguments: + +* **Input data:** a typed object containing event details. Each hook type has its own input shape (for example, `PreToolUseHookInput` includes `tool_name` and `tool_input`, while `NotificationHookInput` includes `message`). See the full type definitions in the [TypeScript](/en/agent-sdk/typescript#hook-input) and [Python](/en/agent-sdk/python#hook-input) SDK references. + * All hook inputs share `session_id`, `cwd`, and `hook_event_name`. + * `agent_id` and `agent_type` are populated when the hook fires inside a subagent. In TypeScript, these are on the base hook input and available to all hook types. In Python, they are on `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` only. +* **Tool use ID** (`str | None` / `string | undefined`): correlates `PreToolUse` and `PostToolUse` events for the same tool call. +* **Context:** in TypeScript, contains a `signal` property (`AbortSignal`) for cancellation. In Python, this argument is reserved for future use. + +#### Outputs + +Your callback returns an object with two categories of fields: + +* **Top-level fields** control the conversation: `systemMessage` injects a message into the conversation visible to the model, and `continue` (`continue_` in Python) determines whether the agent keeps running after this hook. +* **`hookSpecificOutput`** controls the current operation. The fields inside depend on the hook event type. For `PreToolUse` hooks, this is where you set `permissionDecision` (`"allow"`, `"deny"`, or `"ask"`), `permissionDecisionReason`, and `updatedInput`. For `PostToolUse` hooks, you can set `additionalContext` to append information to the tool result. + +Return `{}` to allow the operation without changes. SDK callback hooks use the same JSON output format as [Claude Code shell command hooks](/en/hooks#json-output), which documents every field and event-specific option. For the SDK type definitions, see the [TypeScript](/en/agent-sdk/typescript#sync-hook-json-output) and [Python](/en/agent-sdk/python#sync-hook-json-output) SDK references. + + + When multiple hooks or permission rules apply, **deny** takes priority over **ask**, which takes priority over **allow**. If any hook returns `deny`, the operation is blocked regardless of other hooks. + + +#### Asynchronous output + +By default, the agent waits for your hook to return before proceeding. If your hook performs a side effect (logging, sending a webhook) and doesn't need to influence the agent's behavior, you can return an async output instead. This tells the agent to continue immediately without waiting for the hook to finish: + + + ```python Python theme={null} + async def async_hook(input_data, tool_use_id, context): + # Start a background task, then return immediately + asyncio.create_task(send_to_logging_service(input_data)) + return {"async_": True, "asyncTimeout": 30000} + ``` + + ```typescript TypeScript theme={null} + const asyncHook: HookCallback = async (input, toolUseID, { signal }) => { + // Start a background task, then return immediately + sendToLoggingService(input).catch(console.error); + return { async: true, asyncTimeout: 30000 }; + }; + ``` + + +| Field | Type | Description | +| -------------- | -------- | -------------------------------------------------------------------------------------------------------------- | +| `async` | `true` | Signals async mode. The agent proceeds without waiting. In Python, use `async_` to avoid the reserved keyword. | +| `asyncTimeout` | `number` | Optional timeout in milliseconds for the background operation | + + + Async outputs cannot block, modify, or inject context into the operation since the agent has already moved on. Use them only for side effects like logging, metrics, or notifications. + + +## Examples + +### Modify tool input + +This example intercepts Write tool calls and rewrites the `file_path` argument to prepend `/sandbox`, redirecting all file writes to a sandboxed directory. The callback returns `updatedInput` with the modified path and `permissionDecision: 'allow'` to auto-approve the rewritten operation: + + + ```python Python theme={null} + async def redirect_to_sandbox(input_data, tool_use_id, context): + if input_data["hook_event_name"] != "PreToolUse": + return {} + + if input_data["tool_name"] == "Write": + original_path = input_data["tool_input"].get("file_path", "") + return { + "hookSpecificOutput": { + "hookEventName": input_data["hook_event_name"], + "permissionDecision": "allow", + "updatedInput": { + **input_data["tool_input"], + "file_path": f"/sandbox{original_path}", + }, + } + } + return {} + ``` + + ```typescript TypeScript theme={null} + const redirectToSandbox: HookCallback = async (input, toolUseID, { signal }) => { + if (input.hook_event_name !== "PreToolUse") return {}; + + const preInput = input as PreToolUseHookInput; + const toolInput = preInput.tool_input as Record; + if (preInput.tool_name === "Write") { + const originalPath = toolInput.file_path as string; + return { + hookSpecificOutput: { + hookEventName: preInput.hook_event_name, + permissionDecision: "allow", + updatedInput: { + ...toolInput, + file_path: `/sandbox${originalPath}` + } + } + }; + } + return {}; + }; + ``` + + + + When using `updatedInput`, you must also include `permissionDecision: 'allow'`. Always return a new object rather than mutating the original `tool_input`. + + +### Add context and block a tool + +This example blocks any attempt to write to the `/etc` directory and uses two output fields together: `permissionDecision: 'deny'` stops the tool call, while `systemMessage` injects a reminder into the conversation so the agent receives context about why the operation was blocked and avoids retrying it: + + + ```python Python theme={null} + async def block_etc_writes(input_data, tool_use_id, context): + file_path = input_data["tool_input"].get("file_path", "") + + if file_path.startswith("/etc"): + return { + # Top-level field: inject guidance into the conversation + "systemMessage": "Remember: system directories like /etc are protected.", + # hookSpecificOutput: block the operation + "hookSpecificOutput": { + "hookEventName": input_data["hook_event_name"], + "permissionDecision": "deny", + "permissionDecisionReason": "Writing to /etc is not allowed", + }, + } + return {} + ``` + + ```typescript TypeScript theme={null} + const blockEtcWrites: HookCallback = async (input, toolUseID, { signal }) => { + const preInput = input as PreToolUseHookInput; + const toolInput = preInput.tool_input as Record; + const filePath = toolInput?.file_path as string; + + if (filePath?.startsWith("/etc")) { + return { + // Top-level field: inject guidance into the conversation + systemMessage: "Remember: system directories like /etc are protected.", + // hookSpecificOutput: block the operation + hookSpecificOutput: { + hookEventName: preInput.hook_event_name, + permissionDecision: "deny", + permissionDecisionReason: "Writing to /etc is not allowed" + } + }; + } + return {}; + }; + ``` + + +### Auto-approve specific tools + +By default, the agent may prompt for permission before using certain tools. This example auto-approves read-only filesystem tools (Read, Glob, Grep) by returning `permissionDecision: 'allow'`, letting them run without user confirmation while leaving all other tools subject to normal permission checks: + + + ```python Python theme={null} + async def auto_approve_read_only(input_data, tool_use_id, context): + if input_data["hook_event_name"] != "PreToolUse": + return {} + + read_only_tools = ["Read", "Glob", "Grep"] + if input_data["tool_name"] in read_only_tools: + return { + "hookSpecificOutput": { + "hookEventName": input_data["hook_event_name"], + "permissionDecision": "allow", + "permissionDecisionReason": "Read-only tool auto-approved", + } + } + return {} + ``` + + ```typescript TypeScript theme={null} + const autoApproveReadOnly: HookCallback = async (input, toolUseID, { signal }) => { + if (input.hook_event_name !== "PreToolUse") return {}; + + const preInput = input as PreToolUseHookInput; + const readOnlyTools = ["Read", "Glob", "Grep"]; + if (readOnlyTools.includes(preInput.tool_name)) { + return { + hookSpecificOutput: { + hookEventName: preInput.hook_event_name, + permissionDecision: "allow", + permissionDecisionReason: "Read-only tool auto-approved" + } + }; + } + return {}; + }; + ``` + + +### Chain multiple hooks + +Hooks execute in the order they appear in the array. Keep each hook focused on a single responsibility and chain multiple hooks for complex logic: + + + ```python Python theme={null} + options = ClaudeAgentOptions( + hooks={ + "PreToolUse": [ + HookMatcher(hooks=[rate_limiter]), # First: check rate limits + HookMatcher(hooks=[authorization_check]), # Second: verify permissions + HookMatcher(hooks=[input_sanitizer]), # Third: sanitize inputs + HookMatcher(hooks=[audit_logger]), # Last: log the action + ] + } + ) + ``` + + ```typescript TypeScript theme={null} + const options = { + hooks: { + PreToolUse: [ + { hooks: [rateLimiter] }, // First: check rate limits + { hooks: [authorizationCheck] }, // Second: verify permissions + { hooks: [inputSanitizer] }, // Third: sanitize inputs + { hooks: [auditLogger] } // Last: log the action + ] + } + }; + ``` + + +### Filter with regex matchers + +Use regex patterns to match multiple tools. This example registers three matchers with different scopes: the first triggers `file_security_hook` only for file modification tools, the second triggers `mcp_audit_hook` for any MCP tool (tools whose names start with `mcp__`), and the third triggers `global_logger` for every tool call regardless of name: + + + ```python Python theme={null} + options = ClaudeAgentOptions( + hooks={ + "PreToolUse": [ + # Match file modification tools + HookMatcher(matcher="Write|Edit|Delete", hooks=[file_security_hook]), + # Match all MCP tools + HookMatcher(matcher="^mcp__", hooks=[mcp_audit_hook]), + # Match everything (no matcher) + HookMatcher(hooks=[global_logger]), + ] + } + ) + ``` + + ```typescript TypeScript theme={null} + const options = { + hooks: { + PreToolUse: [ + // Match file modification tools + { matcher: "Write|Edit|Delete", hooks: [fileSecurityHook] }, + + // Match all MCP tools + { matcher: "^mcp__", hooks: [mcpAuditHook] }, + + // Match everything (no matcher) + { hooks: [globalLogger] } + ] + } + }; + ``` + + +### Track subagent activity + +Use `SubagentStop` hooks to monitor when subagents finish their work. See the full input type in the [TypeScript](/en/agent-sdk/typescript#hook-input) and [Python](/en/agent-sdk/python#hook-input) SDK references. This example logs a summary each time a subagent completes: + + + ```python Python theme={null} + async def subagent_tracker(input_data, tool_use_id, context): + # Log subagent details when it finishes + print(f"[SUBAGENT] Completed: {input_data['agent_id']}") + print(f" Transcript: {input_data['agent_transcript_path']}") + print(f" Tool use ID: {tool_use_id}") + print(f" Stop hook active: {input_data.get('stop_hook_active')}") + return {} + + + options = ClaudeAgentOptions( + hooks={"SubagentStop": [HookMatcher(hooks=[subagent_tracker])]} + ) + ``` + + ```typescript TypeScript theme={null} + import { HookCallback, SubagentStopHookInput } from "@anthropic-ai/claude-agent-sdk"; + + const subagentTracker: HookCallback = async (input, toolUseID, { signal }) => { + // Cast to SubagentStopHookInput to access subagent-specific fields + const subInput = input as SubagentStopHookInput; + + // Log subagent details when it finishes + console.log(`[SUBAGENT] Completed: ${subInput.agent_id}`); + console.log(` Transcript: ${subInput.agent_transcript_path}`); + console.log(` Tool use ID: ${toolUseID}`); + console.log(` Stop hook active: ${subInput.stop_hook_active}`); + return {}; + }; + + const options = { + hooks: { + SubagentStop: [{ hooks: [subagentTracker] }] + } + }; + ``` + + +### Make HTTP requests from hooks + +Hooks can perform asynchronous operations like HTTP requests. Catch errors inside your hook instead of letting them propagate, since an unhandled exception can interrupt the agent. + +This example sends a webhook after each tool completes, logging which tool ran and when. The hook catches errors so a failed webhook doesn't interrupt the agent: + + + ```python Python theme={null} + import asyncio + import json + import urllib.request + from datetime import datetime + + + def _send_webhook(tool_name): + """Synchronous helper that POSTs tool usage data to an external webhook.""" + data = json.dumps( + { + "tool": tool_name, + "timestamp": datetime.now().isoformat(), + } + ).encode() + req = urllib.request.Request( + "https://api.example.com/webhook", + data=data, + headers={"Content-Type": "application/json"}, + method="POST", + ) + urllib.request.urlopen(req) + + + async def webhook_notifier(input_data, tool_use_id, context): + # Only fire after a tool completes (PostToolUse), not before + if input_data["hook_event_name"] != "PostToolUse": + return {} + + try: + # Run the blocking HTTP call in a thread to avoid blocking the event loop + await asyncio.to_thread(_send_webhook, input_data["tool_name"]) + except Exception as e: + # Log the error but don't raise. A failed webhook shouldn't stop the agent + print(f"Webhook request failed: {e}") + + return {} + ``` + + ```typescript TypeScript theme={null} + import { query, HookCallback, PostToolUseHookInput } from "@anthropic-ai/claude-agent-sdk"; + + const webhookNotifier: HookCallback = async (input, toolUseID, { signal }) => { + // Only fire after a tool completes (PostToolUse), not before + if (input.hook_event_name !== "PostToolUse") return {}; + + try { + await fetch("https://api.example.com/webhook", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + tool: (input as PostToolUseHookInput).tool_name, + timestamp: new Date().toISOString() + }), + // Pass signal so the request cancels if the hook times out + signal + }); + } catch (error) { + // Handle cancellation separately from other errors + if (error instanceof Error && error.name === "AbortError") { + console.log("Webhook request cancelled"); + } + // Don't re-throw. A failed webhook shouldn't stop the agent + } + + return {}; + }; + + // Register as a PostToolUse hook + for await (const message of query({ + prompt: "Refactor the auth module", + options: { + hooks: { + PostToolUse: [{ hooks: [webhookNotifier] }] + } + } + })) { + console.log(message); + } + ``` + + +### Forward notifications to Slack + +Use `Notification` hooks to receive system notifications from the agent and forward them to external services. Notifications fire for specific event types: `permission_prompt` (Claude needs permission), `idle_prompt` (Claude is waiting for input), `auth_success` (authentication completed), and `elicitation_dialog` (Claude is prompting the user). Each notification includes a `message` field with a human-readable description and optionally a `title`. + +This example forwards every notification to a Slack channel. It requires a [Slack incoming webhook URL](https://api.slack.com/messaging/webhooks), which you create by adding an app to your Slack workspace and enabling incoming webhooks: + + + ```python Python theme={null} + import asyncio + import json + import urllib.request + + from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher + + + def _send_slack_notification(message): + """Synchronous helper that sends a message to Slack via incoming webhook.""" + data = json.dumps({"text": f"Agent status: {message}"}).encode() + req = urllib.request.Request( + "https://hooks.slack.com/services/YOUR/WEBHOOK/URL", + data=data, + headers={"Content-Type": "application/json"}, + method="POST", + ) + urllib.request.urlopen(req) + + + async def notification_handler(input_data, tool_use_id, context): + try: + # Run the blocking HTTP call in a thread to avoid blocking the event loop + await asyncio.to_thread(_send_slack_notification, input_data.get("message", "")) + except Exception as e: + print(f"Failed to send notification: {e}") + + # Return empty object. Notification hooks don't modify agent behavior + return {} + + + async def main(): + options = ClaudeAgentOptions( + hooks={ + # Register the hook for Notification events (no matcher needed) + "Notification": [HookMatcher(hooks=[notification_handler])], + }, + ) + + async with ClaudeSDKClient(options=options) as client: + await client.query("Analyze this codebase") + async for message in client.receive_response(): + print(message) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query, HookCallback, NotificationHookInput } from "@anthropic-ai/claude-agent-sdk"; + + // Define a hook callback that sends notifications to Slack + const notificationHandler: HookCallback = async (input, toolUseID, { signal }) => { + // Cast to NotificationHookInput to access the message field + const notification = input as NotificationHookInput; + + try { + // POST the notification message to a Slack incoming webhook + await fetch("https://hooks.slack.com/services/YOUR/WEBHOOK/URL", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + text: `Agent status: ${notification.message}` + }), + // Pass signal so the request cancels if the hook times out + signal + }); + } catch (error) { + if (error instanceof Error && error.name === "AbortError") { + console.log("Notification cancelled"); + } else { + console.error("Failed to send notification:", error); + } + } + + // Return empty object. Notification hooks don't modify agent behavior + return {}; + }; + + // Register the hook for Notification events (no matcher needed) + for await (const message of query({ + prompt: "Analyze this codebase", + options: { + hooks: { + Notification: [{ hooks: [notificationHandler] }] + } + } + })) { + console.log(message); + } + ``` + + +## Fix common issues + +### Hook not firing + +* Verify the hook event name is correct and case-sensitive (`PreToolUse`, not `preToolUse`) +* Check that your matcher pattern matches the tool name exactly +* Ensure the hook is under the correct event type in `options.hooks` +* For non-tool hooks like `Stop` and `SubagentStop`, matchers match against different fields (see [matcher patterns](/en/hooks#matcher-patterns)) +* Hooks may not fire when the agent hits the [`max_turns`](/en/agent-sdk/python#claude-agent-options) limit because the session ends before hooks can execute + +### Matcher not filtering as expected + +Matchers only match **tool names**, not file paths or other arguments. To filter by file path, check `tool_input.file_path` inside your hook: + +```typescript theme={null} +const myHook: HookCallback = async (input, toolUseID, { signal }) => { + const preInput = input as PreToolUseHookInput; + const toolInput = preInput.tool_input as Record; + const filePath = toolInput?.file_path as string; + if (!filePath?.endsWith(".md")) return {}; // Skip non-markdown files + // Process markdown files... + return {}; +}; +``` + +### Hook timeout + +* Increase the `timeout` value in the `HookMatcher` configuration +* Use the `AbortSignal` from the third callback argument to handle cancellation gracefully in TypeScript + +### Tool blocked unexpectedly + +* Check all `PreToolUse` hooks for `permissionDecision: 'deny'` returns +* Add logging to your hooks to see what `permissionDecisionReason` they're returning +* Verify matcher patterns aren't too broad (an empty matcher matches all tools) + +### Modified input not applied + +* Ensure `updatedInput` is inside `hookSpecificOutput`, not at the top level: + + ```typescript theme={null} + return { + hookSpecificOutput: { + hookEventName: "PreToolUse", + permissionDecision: "allow", + updatedInput: { command: "new command" } + } + }; + ``` + +* You must also return `permissionDecision: 'allow'` for the input modification to take effect + +* Include `hookEventName` in `hookSpecificOutput` to identify which hook type the output is for + +### Session hooks not available in Python + +`SessionStart` and `SessionEnd` can be registered as SDK callback hooks in TypeScript, but are not available in the Python SDK (`HookEvent` omits them). In Python, they are only available as [shell command hooks](/en/hooks#hook-events) defined in settings files (for example, `.claude/settings.json`). To load shell command hooks from your SDK application, include the appropriate setting source with [`setting_sources`](/en/agent-sdk/python#setting-source) or [`settingSources`](/en/agent-sdk/typescript#setting-source): + + + ```python Python theme={null} + options = ClaudeAgentOptions( + setting_sources=["project"], # Loads .claude/settings.json including hooks + ) + ``` + + ```typescript TypeScript theme={null} + const options = { + settingSources: ["project"] // Loads .claude/settings.json including hooks + }; + ``` + + +To run initialization logic as a Python SDK callback instead, use the first message from `client.receive_response()` as your trigger. + +### Subagent permission prompts multiplying + +When spawning multiple subagents, each one may request permissions separately. Subagents do not automatically inherit parent agent permissions. To avoid repeated prompts, use `PreToolUse` hooks to auto-approve specific tools, or configure permission rules that apply to subagent sessions. + +### Recursive hook loops with subagents + +A `UserPromptSubmit` hook that spawns subagents can create infinite loops if those subagents trigger the same hook. To prevent this: + +* Check for a subagent indicator in the hook input before spawning +* Use a shared variable or session state to track whether you're already inside a subagent +* Scope hooks to only run for the top-level agent session + +### systemMessage not appearing in output + +The `systemMessage` field adds context to the conversation that the model sees, but it may not appear in all SDK output modes. If you need to surface hook decisions to your application, log them separately or use a dedicated output channel. + +## Related resources + +* [Claude Code hooks reference](/en/hooks): full JSON input/output schemas, event documentation, and matcher patterns +* [Claude Code hooks guide](/en/hooks-guide): shell command hook examples and walkthroughs +* [TypeScript SDK reference](/en/agent-sdk/typescript): hook types, input/output definitions, and configuration options +* [Python SDK reference](/en/agent-sdk/python): hook types, input/output definitions, and configuration options +* [Permissions](/en/agent-sdk/permissions): control what your agent can do +* [Custom tools](/en/agent-sdk/custom-tools): build tools to extend agent capabilities diff --git a/content/en/docs/claude-code/agent-sdk/hosting.md b/content/en/docs/claude-code/agent-sdk/hosting.md new file mode 100644 index 000000000..58d693b86 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/hosting.md @@ -0,0 +1,142 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Hosting the Agent SDK + +> Deploy and host Claude Agent SDK in production environments + +The Claude Agent SDK differs from traditional stateless LLM APIs in that it maintains conversational state and executes commands in a persistent environment. This guide covers the architecture, hosting considerations, and best practices for deploying SDK-based agents in production. + + + For security hardening beyond basic sandboxing (including network controls, credential management, and isolation options), see [Secure Deployment](/en/agent-sdk/secure-deployment). + + +## Hosting Requirements + +### Container-Based Sandboxing + +For security and isolation, the SDK should run inside a sandboxed container environment. This provides process isolation, resource limits, network control, and ephemeral filesystems. + +The SDK also supports [programmatic sandbox configuration](/en/agent-sdk/typescript#sandbox-settings) for command execution. + +### System Requirements + +Each SDK instance requires: + +* **Runtime dependencies** + * Python 3.10+ (for Python SDK) or Node.js 18+ (for TypeScript SDK) + * Node.js (required by the bundled Claude Code CLI that the SDK spawns; both SDK packages include it, so no separate install is needed) + +* **Resource allocation** + * Recommended: 1GiB RAM, 5GiB of disk, and 1 CPU (vary this based on your task as needed) + +* **Network access** + * Outbound HTTPS to `api.anthropic.com` + * Optional: Access to MCP servers or external tools + +## Understanding the SDK Architecture + +Unlike stateless API calls, the Claude Agent SDK operates as a **long-running process** that: + +* **Executes commands** in a persistent shell environment +* **Manages file operations** within a working directory +* **Handles tool execution** with context from previous interactions + +## Sandbox Provider Options + +Several providers specialize in secure container environments for AI code execution: + +* **[Modal Sandbox](https://modal.com/docs/guide/sandbox)** - [demo implementation](https://modal.com/docs/examples/claude-slack-gif-creator) +* **[Cloudflare Sandboxes](https://github.com/cloudflare/sandbox-sdk)** +* **[Daytona](https://www.daytona.io/)** +* **[E2B](https://e2b.dev/)** +* **[Fly Machines](https://fly.io/docs/machines/)** +* **[Vercel Sandbox](https://vercel.com/docs/functions/sandbox)** + +For self-hosted options (Docker, gVisor, Firecracker) and detailed isolation configuration, see [Isolation Technologies](/en/agent-sdk/secure-deployment#isolation-technologies). + +## Production Deployment Patterns + +### Pattern 1: Ephemeral Sessions + +Create a new container for each user task, then destroy it when complete. + +Best for one-off tasks, the user may still interact with the AI while the task is completing, but once completed the container is destroyed. + +**Examples:** + +* Bug Investigation & Fix: Debug and resolve a specific issue with relevant context +* Invoice Processing: Extract and structure data from receipts/invoices for accounting systems +* Translation Tasks: Translate documents or content batches between languages +* Image/Video Processing: Apply transformations, optimizations, or extract metadata from media files + +### Pattern 2: Long-Running Sessions + +Maintain persistent container instances for long running tasks. Often times running *multiple* Claude Agent processes inside of the container based on demand. + +Best for proactive agents that take action without the users input, agents that serve content or agents that process high amounts of messages. + +**Examples:** + +* Email Agent: Monitors incoming emails and autonomously triages, responds, or takes actions based on content +* Site Builder: Hosts custom websites per user with live editing capabilities served through container ports +* High-Frequency Chat Bots: Handles continuous message streams from platforms like Slack where rapid response times are critical + +### Pattern 3: Hybrid Sessions + +Ephemeral containers that are hydrated with history and state, possibly from a database or from the SDK's session resumption features. + +Best for containers with intermittent interaction from the user that kicks off work and spins down when the work is completed but can be continued. + +**Examples:** + +* Personal Project Manager: Helps manage ongoing projects with intermittent check-ins, maintains context of tasks, decisions, and progress +* Deep Research: Conducts multi-hour research tasks, saves findings and resumes investigation when user returns +* Customer Support Agent: Handles support tickets that span multiple interactions, loads ticket history and customer context + +### Pattern 4: Single Containers + +Run multiple Claude Agent SDK processes in one global container. + +Best for agents that must collaborate closely together. This is likely the least popular pattern because you will have to prevent agents from overwriting each other. + +**Examples:** + +* **Simulations**: Agents that interact with each other in simulations such as video games. + +## FAQ + +### How do I communicate with my sandboxes? + +When hosting in containers, expose ports to communicate with your SDK instances. Your application can expose HTTP/WebSocket endpoints for external clients while the SDK runs internally within the container. + +### What is the cost of hosting a container? + +The dominant cost of serving agents is the tokens; containers vary based on what you provision, but a minimum cost is roughly 5 cents per hour running. + +### When should I shut down idle containers vs. keeping them warm? + +This is likely provider dependent, different sandbox providers will let you set different criteria for idle timeouts after which a sandbox might spin down. +You will want to tune this timeout based on how frequent you think user response might be. + +### How often should I update the Claude Code CLI? + +The Claude Code CLI is versioned with semver, so any breaking changes will be versioned. + +### How do I monitor container health and agent performance? + +Since containers are just servers the same logging infrastructure you use for the backend will work for containers. + +### How long can an agent session run before timing out? + +An agent session will not timeout, but consider setting a 'maxTurns' property to prevent Claude from getting stuck in a loop. + +## Next Steps + +* [Secure Deployment](/en/agent-sdk/secure-deployment) - Network controls, credential management, and isolation hardening +* [TypeScript SDK - Sandbox Settings](/en/agent-sdk/typescript#sandbox-settings) - Configure sandbox programmatically +* [Sessions Guide](/en/agent-sdk/sessions) - Learn about session management +* [Permissions](/en/agent-sdk/permissions) - Configure tool permissions +* [Cost Tracking](/en/agent-sdk/cost-tracking) - Monitor API usage +* [MCP Integration](/en/agent-sdk/mcp) - Extend with custom tools diff --git a/content/en/docs/claude-code/agent-sdk/mcp.md b/content/en/docs/claude-code/agent-sdk/mcp.md new file mode 100644 index 000000000..b976a2cb2 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/mcp.md @@ -0,0 +1,768 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Connect to external tools with MCP + +> Configure MCP servers to extend your agent with external tools. Covers transport types, tool search for large tool sets, authentication, and error handling. + +The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) is an open standard for connecting AI agents to external tools and data sources. With MCP, your agent can query databases, integrate with APIs like Slack and GitHub, and connect to other services without writing custom tool implementations. + +MCP servers can run as local processes, connect over HTTP, or execute directly within your SDK application. + +## Quickstart + +This example connects to the [Claude Code documentation](https://code.claude.com/docs) MCP server using [HTTP transport](#httpsse-servers) and uses [`allowedTools`](#allow-mcp-tools) with a wildcard to permit all tools from the server. + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Use the docs MCP server to explain what hooks are in Claude Code", + options: { + mcpServers: { + "claude-code-docs": { + type: "http", + url: "https://code.claude.com/docs/mcp" + } + }, + allowedTools: ["mcp__claude-code-docs__*"] + } + })) { + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + + async def main(): + options = ClaudeAgentOptions( + mcp_servers={ + "claude-code-docs": { + "type": "http", + "url": "https://code.claude.com/docs/mcp", + } + }, + allowed_tools=["mcp__claude-code-docs__*"], + ) + + async for message in query( + prompt="Use the docs MCP server to explain what hooks are in Claude Code", + options=options, + ): + if isinstance(message, ResultMessage) and message.subtype == "success": + print(message.result) + + + asyncio.run(main()) + ``` + + +The agent connects to the documentation server, searches for information about hooks, and returns the results. + +## Add an MCP server + +You can configure MCP servers in code when calling `query()`, or in a `.mcp.json` file loaded via [`settingSources`](#from-a-config-file). + +### In code + +Pass MCP servers directly in the `mcpServers` option: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "List files in my project", + options: { + mcpServers: { + filesystem: { + command: "npx", + args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"] + } + }, + allowedTools: ["mcp__filesystem__*"] + } + })) { + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + + async def main(): + options = ClaudeAgentOptions( + mcp_servers={ + "filesystem": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "/Users/me/projects", + ], + } + }, + allowed_tools=["mcp__filesystem__*"], + ) + + async for message in query(prompt="List files in my project", options=options): + if isinstance(message, ResultMessage) and message.subtype == "success": + print(message.result) + + + asyncio.run(main()) + ``` + + +### From a config file + +Create a `.mcp.json` file at your project root. The SDK does not load filesystem settings by default, so set `settingSources: ["project"]` (Python: `setting_sources=["project"]`) in your options for the file to be picked up: + +```json theme={null} +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"] + } + } +} +``` + +## Allow MCP tools + +MCP tools require explicit permission before Claude can use them. Without permission, Claude will see that tools are available but won't be able to call them. + +### Tool naming convention + +MCP tools follow the naming pattern `mcp____`. For example, a GitHub server named `"github"` with a `list_issues` tool becomes `mcp__github__list_issues`. + +### Grant access with allowedTools + +Use `allowedTools` to specify which MCP tools Claude can use: + +```typescript hidelines={1,-1} theme={null} +const _ = { + options: { + mcpServers: { + // your servers + }, + allowedTools: [ + "mcp__github__*", // All tools from the github server + "mcp__db__query", // Only the query tool from db server + "mcp__slack__send_message" // Only send_message from slack server + ] + } +}; +``` + +Wildcards (`*`) let you allow all tools from a server without listing each one individually. + + + **Prefer `allowedTools` over permission modes for MCP access.** `permissionMode: "acceptEdits"` does not auto-approve MCP tools (only file edits and filesystem Bash commands). `permissionMode: "bypassPermissions"` does auto-approve MCP tools but also disables all other safety prompts, which is broader than necessary. A wildcard in `allowedTools` grants exactly the MCP server you want and nothing more. See [Permission modes](/en/agent-sdk/permissions#permission-modes) for a full comparison. + + +### Discover available tools + +To see what tools an MCP server provides, check the server's documentation or connect to the server and inspect the `system` init message: + +```typescript theme={null} +for await (const message of query({ prompt: "...", options })) { + if (message.type === "system" && message.subtype === "init") { + console.log("Available MCP tools:", message.mcp_servers); + } +} +``` + +## Transport types + +MCP servers communicate with your agent using different transport protocols. Check the server's documentation to see which transport it supports: + +* If the docs give you a **command to run** (like `npx @modelcontextprotocol/server-github`), use stdio +* If the docs give you a **URL**, use HTTP or SSE +* If you're building your own tools in code, use an SDK MCP server + +### stdio servers + +Local processes that communicate via stdin/stdout. Use this for MCP servers you run on the same machine: + + + + + ```typescript TypeScript hidelines={1,-1} theme={null} + const _ = { + options: { + mcpServers: { + github: { + command: "npx", + args: ["-y", "@modelcontextprotocol/server-github"], + env: { + GITHUB_TOKEN: process.env.GITHUB_TOKEN + } + } + }, + allowedTools: ["mcp__github__list_issues", "mcp__github__search_issues"] + } + }; + ``` + + ```python Python theme={null} + options = ClaudeAgentOptions( + mcp_servers={ + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]}, + } + }, + allowed_tools=["mcp__github__list_issues", "mcp__github__search_issues"], + ) + ``` + + + + + ```json theme={null} + { + "mcpServers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } + } + ``` + + + +### HTTP/SSE servers + +Use HTTP or SSE for cloud-hosted MCP servers and remote APIs: + + + + + ```typescript TypeScript hidelines={1,-1} theme={null} + const _ = { + options: { + mcpServers: { + "remote-api": { + type: "sse", + url: "https://api.example.com/mcp/sse", + headers: { + Authorization: `Bearer ${process.env.API_TOKEN}` + } + } + }, + allowedTools: ["mcp__remote-api__*"] + } + }; + ``` + + ```python Python theme={null} + options = ClaudeAgentOptions( + mcp_servers={ + "remote-api": { + "type": "sse", + "url": "https://api.example.com/mcp/sse", + "headers": {"Authorization": f"Bearer {os.environ['API_TOKEN']}"}, + } + }, + allowed_tools=["mcp__remote-api__*"], + ) + ``` + + + + + ```json theme={null} + { + "mcpServers": { + "remote-api": { + "type": "sse", + "url": "https://api.example.com/mcp/sse", + "headers": { + "Authorization": "Bearer ${API_TOKEN}" + } + } + } + } + ``` + + + +For HTTP (non-streaming), use `"type": "http"` instead. + +### SDK MCP servers + +Define custom tools directly in your application code instead of running a separate server process. See the [custom tools guide](/en/agent-sdk/custom-tools) for implementation details. + +## MCP tool search + +When you have many MCP tools configured, tool definitions can consume a significant portion of your context window. Tool search solves this by withholding tool definitions from context and loading only the ones Claude needs for each turn. + +Tool search is enabled by default. See [Tool search](/en/agent-sdk/tool-search) for configuration options and details. + +For more detail, including best practices and using tool search with custom SDK tools, see the [tool search guide](/en/agent-sdk/tool-search). + +## Authentication + +Most MCP servers require authentication to access external services. Pass credentials through environment variables in the server configuration. + +### Pass credentials via environment variables + +Use the `env` field to pass API keys, tokens, and other credentials to the MCP server: + + + + + ```typescript TypeScript hidelines={1,-1} theme={null} + const _ = { + options: { + mcpServers: { + github: { + command: "npx", + args: ["-y", "@modelcontextprotocol/server-github"], + env: { + GITHUB_TOKEN: process.env.GITHUB_TOKEN + } + } + }, + allowedTools: ["mcp__github__list_issues"] + } + }; + ``` + + ```python Python theme={null} + options = ClaudeAgentOptions( + mcp_servers={ + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]}, + } + }, + allowed_tools=["mcp__github__list_issues"], + ) + ``` + + + + + ```json theme={null} + { + "mcpServers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } + } + ``` + + The `${GITHUB_TOKEN}` syntax expands environment variables at runtime. + + + +See [List issues from a repository](#list-issues-from-a-repository) for a complete working example with debug logging. + +### HTTP headers for remote servers + +For HTTP and SSE servers, pass authentication headers directly in the server configuration: + + + + + ```typescript TypeScript hidelines={1,-1} theme={null} + const _ = { + options: { + mcpServers: { + "secure-api": { + type: "http", + url: "https://api.example.com/mcp", + headers: { + Authorization: `Bearer ${process.env.API_TOKEN}` + } + } + }, + allowedTools: ["mcp__secure-api__*"] + } + }; + ``` + + ```python Python theme={null} + options = ClaudeAgentOptions( + mcp_servers={ + "secure-api": { + "type": "http", + "url": "https://api.example.com/mcp", + "headers": {"Authorization": f"Bearer {os.environ['API_TOKEN']}"}, + } + }, + allowed_tools=["mcp__secure-api__*"], + ) + ``` + + + + + ```json theme={null} + { + "mcpServers": { + "secure-api": { + "type": "http", + "url": "https://api.example.com/mcp", + "headers": { + "Authorization": "Bearer ${API_TOKEN}" + } + } + } + } + ``` + + The `${API_TOKEN}` syntax expands environment variables at runtime. + + + +### OAuth2 authentication + +The [MCP specification supports OAuth 2.1](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) for authorization. The SDK doesn't handle OAuth flows automatically, but you can pass access tokens via headers after completing the OAuth flow in your application: + + + ```typescript TypeScript theme={null} + // After completing OAuth flow in your app + const accessToken = await getAccessTokenFromOAuthFlow(); + + const options = { + mcpServers: { + "oauth-api": { + type: "http", + url: "https://api.example.com/mcp", + headers: { + Authorization: `Bearer ${accessToken}` + } + } + }, + allowedTools: ["mcp__oauth-api__*"] + }; + ``` + + ```python Python theme={null} + # After completing OAuth flow in your app + access_token = await get_access_token_from_oauth_flow() + + options = ClaudeAgentOptions( + mcp_servers={ + "oauth-api": { + "type": "http", + "url": "https://api.example.com/mcp", + "headers": {"Authorization": f"Bearer {access_token}"}, + } + }, + allowed_tools=["mcp__oauth-api__*"], + ) + ``` + + +## Examples + +### List issues from a repository + +This example connects to the [GitHub MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/github) to list recent issues. The example includes debug logging to verify the MCP connection and tool calls. + +Before running, create a [GitHub personal access token](https://github.com/settings/tokens) with `repo` scope and set it as an environment variable: + +```bash theme={null} +export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx +``` + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "List the 3 most recent issues in anthropics/claude-code", + options: { + mcpServers: { + github: { + command: "npx", + args: ["-y", "@modelcontextprotocol/server-github"], + env: { + GITHUB_TOKEN: process.env.GITHUB_TOKEN + } + } + }, + allowedTools: ["mcp__github__list_issues"] + } + })) { + // Verify MCP server connected successfully + if (message.type === "system" && message.subtype === "init") { + console.log("MCP servers:", message.mcp_servers); + } + + // Log when Claude calls an MCP tool + if (message.type === "assistant") { + for (const block of message.message.content) { + if (block.type === "tool_use" && block.name.startsWith("mcp__")) { + console.log("MCP tool called:", block.name); + } + } + } + + // Print the final result + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } + } + ``` + + ```python Python theme={null} + import asyncio + import os + from claude_agent_sdk import ( + query, + ClaudeAgentOptions, + ResultMessage, + SystemMessage, + AssistantMessage, + ) + + + async def main(): + options = ClaudeAgentOptions( + mcp_servers={ + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]}, + } + }, + allowed_tools=["mcp__github__list_issues"], + ) + + async for message in query( + prompt="List the 3 most recent issues in anthropics/claude-code", + options=options, + ): + # Verify MCP server connected successfully + if isinstance(message, SystemMessage) and message.subtype == "init": + print("MCP servers:", message.data.get("mcp_servers")) + + # Log when Claude calls an MCP tool + if isinstance(message, AssistantMessage): + for block in message.content: + if hasattr(block, "name") and block.name.startswith("mcp__"): + print("MCP tool called:", block.name) + + # Print the final result + if isinstance(message, ResultMessage) and message.subtype == "success": + print(message.result) + + + asyncio.run(main()) + ``` + + +### Query a database + +This example uses the [Postgres MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres) to query a database. The connection string is passed as an argument to the server. The agent automatically discovers the database schema, writes the SQL query, and returns the results: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Connection string from environment variable + const connectionString = process.env.DATABASE_URL; + + for await (const message of query({ + // Natural language query - Claude writes the SQL + prompt: "How many users signed up last week? Break it down by day.", + options: { + mcpServers: { + postgres: { + command: "npx", + // Pass connection string as argument to the server + args: ["-y", "@modelcontextprotocol/server-postgres", connectionString] + } + }, + // Allow only read queries, not writes + allowedTools: ["mcp__postgres__query"] + } + })) { + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } + } + ``` + + ```python Python theme={null} + import asyncio + import os + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + + async def main(): + # Connection string from environment variable + connection_string = os.environ["DATABASE_URL"] + + options = ClaudeAgentOptions( + mcp_servers={ + "postgres": { + "command": "npx", + # Pass connection string as argument to the server + "args": [ + "-y", + "@modelcontextprotocol/server-postgres", + connection_string, + ], + } + }, + # Allow only read queries, not writes + allowed_tools=["mcp__postgres__query"], + ) + + # Natural language query - Claude writes the SQL + async for message in query( + prompt="How many users signed up last week? Break it down by day.", + options=options, + ): + if isinstance(message, ResultMessage) and message.subtype == "success": + print(message.result) + + + asyncio.run(main()) + ``` + + +## Error handling + +MCP servers can fail to connect for various reasons: the server process might not be installed, credentials might be invalid, or a remote server might be unreachable. + +The SDK emits a `system` message with subtype `init` at the start of each query. This message includes the connection status for each MCP server. Check the `status` field to detect connection failures before the agent starts working: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Process data", + options: { + mcpServers: { + "data-processor": dataServer + } + } + })) { + if (message.type === "system" && message.subtype === "init") { + const failedServers = message.mcp_servers.filter((s) => s.status !== "connected"); + + if (failedServers.length > 0) { + console.warn("Failed to connect:", failedServers); + } + } + + if (message.type === "result" && message.subtype === "error_during_execution") { + console.error("Execution failed"); + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage + + + async def main(): + options = ClaudeAgentOptions(mcp_servers={"data-processor": data_server}) + + async for message in query(prompt="Process data", options=options): + if isinstance(message, SystemMessage) and message.subtype == "init": + failed_servers = [ + s + for s in message.data.get("mcp_servers", []) + if s.get("status") != "connected" + ] + + if failed_servers: + print(f"Failed to connect: {failed_servers}") + + if ( + isinstance(message, ResultMessage) + and message.subtype == "error_during_execution" + ): + print("Execution failed") + + + asyncio.run(main()) + ``` + + +## Troubleshooting + +### Server shows "failed" status + +Check the `init` message to see which servers failed to connect: + +```typescript theme={null} +if (message.type === "system" && message.subtype === "init") { + for (const server of message.mcp_servers) { + if (server.status === "failed") { + console.error(`Server ${server.name} failed to connect`); + } + } +} +``` + +Common causes: + +* **Missing environment variables**: Ensure required tokens and credentials are set. For stdio servers, check the `env` field matches what the server expects. +* **Server not installed**: For `npx` commands, verify the package exists and Node.js is in your PATH. +* **Invalid connection string**: For database servers, verify the connection string format and that the database is accessible. +* **Network issues**: For remote HTTP/SSE servers, check the URL is reachable and any firewalls allow the connection. + +### Tools not being called + +If Claude sees tools but doesn't use them, check that you've granted permission with `allowedTools`: + +```typescript hidelines={1,-1} theme={null} +const _ = { + options: { + mcpServers: { + // your servers + }, + allowedTools: ["mcp__servername__*"] // Required for Claude to use the tools + } +}; +``` + +### Connection timeouts + +The MCP SDK has a default timeout of 60 seconds for server connections. If your server takes longer to start, the connection will fail. For servers that need more startup time, consider: + +* Using a lighter-weight server if available +* Pre-warming the server before starting your agent +* Checking server logs for slow initialization causes + +## Related resources + +* **[Custom tools guide](/en/agent-sdk/custom-tools)**: Build your own MCP server that runs in-process with your SDK application +* **[Permissions](/en/agent-sdk/permissions)**: Control which MCP tools your agent can use with `allowedTools` and `disallowedTools` +* **[TypeScript SDK reference](/en/agent-sdk/typescript)**: Full API reference including MCP configuration options +* **[Python SDK reference](/en/agent-sdk/python)**: Full API reference including MCP configuration options +* **[MCP server directory](https://github.com/modelcontextprotocol/servers)**: Browse available MCP servers for databases, APIs, and more diff --git a/content/en/docs/claude-code/agent-sdk/migration-guide.md b/content/en/docs/claude-code/agent-sdk/migration-guide.md new file mode 100644 index 000000000..d46257e22 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/migration-guide.md @@ -0,0 +1,315 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Migrate to Claude Agent SDK + +> Guide for migrating the Claude Code TypeScript and Python SDKs to the Claude Agent SDK + +## Overview + +The Claude Code SDK has been renamed to the **Claude Agent SDK** and its documentation has been reorganized. This change reflects the SDK's broader capabilities for building AI agents beyond just coding tasks. + +## What's Changed + +| Aspect | Old | New | +| :------------------------- | :-------------------------- | :------------------------------- | +| **Package Name (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` | +| **Python Package** | `claude-code-sdk` | `claude-agent-sdk` | +| **Documentation Location** | Claude Code docs | API Guide → Agent SDK section | + + + **Documentation Changes:** The Agent SDK documentation has moved from the Claude Code docs to the API Guide under a dedicated [Agent SDK](/en/agent-sdk/overview) section. The Claude Code docs now focus on the CLI tool and automation features. + + +## Migration Steps + +### For TypeScript/JavaScript Projects + +**1. Uninstall the old package:** + +```bash theme={null} +npm uninstall @anthropic-ai/claude-code +``` + +**2. Install the new package:** + +```bash theme={null} +npm install @anthropic-ai/claude-agent-sdk +``` + +**3. Update your imports:** + +Change all imports from `@anthropic-ai/claude-code` to `@anthropic-ai/claude-agent-sdk`: + +```typescript theme={null} +// Before +import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code"; + +// After +import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk"; +``` + +**4. Update package.json dependencies:** + +If you have the package listed in your `package.json`, update it: + +Before: + +```json theme={null} +{ + "dependencies": { + "@anthropic-ai/claude-code": "^0.0.42" + } +} +``` + +After: + +```json theme={null} +{ + "dependencies": { + "@anthropic-ai/claude-agent-sdk": "^0.2.0" + } +} +``` + +That's it! No other code changes are required. + +### For Python Projects + +**1. Uninstall the old package:** + +```bash theme={null} +pip uninstall claude-code-sdk +``` + +**2. Install the new package:** + +```bash theme={null} +pip install claude-agent-sdk +``` + +**3. Update your imports:** + +Change all imports from `claude_code_sdk` to `claude_agent_sdk`: + +```python theme={null} +# Before +from claude_code_sdk import query, ClaudeCodeOptions + +# After +from claude_agent_sdk import query, ClaudeAgentOptions +``` + +**4. Update type names:** + +Change `ClaudeCodeOptions` to `ClaudeAgentOptions`: + +```python theme={null} +# Before +from claude_code_sdk import query, ClaudeCodeOptions + +options = ClaudeCodeOptions(model="claude-opus-4-6") + +# After +from claude_agent_sdk import query, ClaudeAgentOptions + +options = ClaudeAgentOptions(model="claude-opus-4-6") +``` + +**5. Review [breaking changes](#breaking-changes)** + +Make any code changes needed to complete the migration. + +## Breaking changes + + + To improve isolation and explicit configuration, Claude Agent SDK v0.1.0 introduces breaking changes for users migrating from Claude Code SDK. Review this section carefully before migrating. + + +### Python: ClaudeCodeOptions renamed to ClaudeAgentOptions + +**What changed:** The Python SDK type `ClaudeCodeOptions` has been renamed to `ClaudeAgentOptions`. + +**Migration:** + +```python theme={null} +# BEFORE (claude-code-sdk) +from claude_code_sdk import query, ClaudeCodeOptions + +options = ClaudeCodeOptions(model="claude-opus-4-6", permission_mode="acceptEdits") + +# AFTER (claude-agent-sdk) +from claude_agent_sdk import query, ClaudeAgentOptions + +options = ClaudeAgentOptions(model="claude-opus-4-6", permission_mode="acceptEdits") +``` + +**Why this changed:** The type name now matches the "Claude Agent SDK" branding and provides consistency across the SDK's naming conventions. + +### System prompt no longer default + +**What changed:** The SDK no longer uses Claude Code's system prompt by default. + +**Migration:** + + + ```typescript TypeScript theme={null} + // BEFORE (v0.0.x) - Used Claude Code's system prompt by default + const result = query({ prompt: "Hello" }); + + // AFTER (v0.1.0) - Uses minimal system prompt by default + // To get the old behavior, explicitly request Claude Code's preset: + const result = query({ + prompt: "Hello", + options: { + systemPrompt: { type: "preset", preset: "claude_code" } + } + }); + + // Or use a custom system prompt: + const result = query({ + prompt: "Hello", + options: { + systemPrompt: "You are a helpful coding assistant" + } + }); + ``` + + ```python Python theme={null} + # BEFORE (v0.0.x) - Used Claude Code's system prompt by default + async for message in query(prompt="Hello"): + print(message) + + # AFTER (v0.1.0) - Uses minimal system prompt by default + # To get the old behavior, explicitly request Claude Code's preset: + from claude_agent_sdk import query, ClaudeAgentOptions + + async for message in query( + prompt="Hello", + options=ClaudeAgentOptions( + system_prompt={"type": "preset", "preset": "claude_code"} # Use the preset + ), + ): + print(message) + + # Or use a custom system prompt: + async for message in query( + prompt="Hello", + options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"), + ): + print(message) + ``` + + +**Why this changed:** Provides better control and isolation for SDK applications. You can now build agents with custom behavior without inheriting Claude Code's CLI-focused instructions. + +### Settings Sources No Longer Loaded by Default + +**What changed:** The SDK no longer reads from filesystem settings (CLAUDE.md, settings.json, slash commands, etc.) by default. + +**Migration:** + + + ```typescript TypeScript theme={null} + // BEFORE (v0.0.x) - Loaded all settings automatically + const result = query({ prompt: "Hello" }); + // Would read from: + // - ~/.claude/settings.json (user) + // - .claude/settings.json (project) + // - .claude/settings.local.json (local) + // - CLAUDE.md files + // - Custom slash commands + + // AFTER (v0.1.0) - No settings loaded by default + // To get the old behavior: + const result = query({ + prompt: "Hello", + options: { + settingSources: ["user", "project", "local"] + } + }); + + // Or load only specific sources: + const result = query({ + prompt: "Hello", + options: { + settingSources: ["project"] // Only project settings + } + }); + ``` + + ```python Python theme={null} + # BEFORE (v0.0.x) - Loaded all settings automatically + async for message in query(prompt="Hello"): + print(message) + # Would read from: + # - ~/.claude/settings.json (user) + # - .claude/settings.json (project) + # - .claude/settings.local.json (local) + # - CLAUDE.md files + # - Custom slash commands + + # AFTER (v0.1.0) - No settings loaded by default + # To get the old behavior: + from claude_agent_sdk import query, ClaudeAgentOptions + + async for message in query( + prompt="Hello", + options=ClaudeAgentOptions(setting_sources=["user", "project", "local"]), + ): + print(message) + + # Or load only specific sources: + async for message in query( + prompt="Hello", + options=ClaudeAgentOptions( + setting_sources=["project"] # Only project settings + ), + ): + print(message) + ``` + + +**Why this changed:** Ensures SDK applications have predictable behavior independent of local filesystem configurations. This is especially important for: + +* **CI/CD environments** - Consistent behavior without local customizations +* **Deployed applications** - No dependency on filesystem settings +* **Testing** - Isolated test environments +* **Multi-tenant systems** - Prevent settings leakage between users + + + **Backward compatibility:** If your application relied on filesystem settings (custom slash commands, CLAUDE.md instructions, etc.), add `settingSources: ['user', 'project', 'local']` to your options. + + +## Why the Rename? + +The Claude Code SDK was originally designed for coding tasks, but it has evolved into a powerful framework for building all types of AI agents. The new name "Claude Agent SDK" better reflects its capabilities: + +* Building business agents (legal assistants, finance advisors, customer support) +* Creating specialized coding agents (SRE bots, security reviewers, code review agents) +* Developing custom agents for any domain with tool use, MCP integration, and more + +## Getting Help + +If you encounter any issues during migration: + +**For TypeScript/JavaScript:** + +1. Check that all imports are updated to use `@anthropic-ai/claude-agent-sdk` +2. Verify your package.json has the new package name +3. Run `npm install` to ensure dependencies are updated + +**For Python:** + +1. Check that all imports are updated to use `claude_agent_sdk` +2. Verify your requirements.txt or pyproject.toml has the new package name +3. Run `pip install claude-agent-sdk` to ensure the package is installed + +## Next Steps + +* Explore the [Agent SDK Overview](/en/agent-sdk/overview) to learn about available features +* Check out the [TypeScript SDK Reference](/en/agent-sdk/typescript) for detailed API documentation +* Review the [Python SDK Reference](/en/agent-sdk/python) for Python-specific documentation +* Learn about [Custom Tools](/en/agent-sdk/custom-tools) and [MCP Integration](/en/agent-sdk/mcp) diff --git a/content/en/docs/claude-code/agent-sdk/modifying-system-prompts.md b/content/en/docs/claude-code/agent-sdk/modifying-system-prompts.md new file mode 100644 index 000000000..4e91cd1e6 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/modifying-system-prompts.md @@ -0,0 +1,474 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Modifying system prompts + +> Learn how to customize Claude's behavior by modifying system prompts using three approaches - output styles, systemPrompt with append, and custom system prompts. + +System prompts define Claude's behavior, capabilities, and response style. The Claude Agent SDK provides three ways to customize system prompts: using output styles (persistent, file-based configurations), appending to Claude Code's prompt, or using a fully custom prompt. + +## Understanding system prompts + +A system prompt is the initial instruction set that shapes how Claude behaves throughout a conversation. + + + **Default behavior:** The Agent SDK uses a **minimal system prompt** by default. It contains only essential tool instructions but omits Claude Code's coding guidelines, response style, and project context. To include the full Claude Code system prompt, specify `systemPrompt: { type: "preset", preset: "claude_code" }` in TypeScript or `system_prompt={"type": "preset", "preset": "claude_code"}` in Python. + + +Claude Code's system prompt includes: + +* Tool usage instructions and available tools +* Code style and formatting guidelines +* Response tone and verbosity settings +* Security and safety instructions +* Context about the current working directory and environment + +## Methods of modification + +### Method 1: CLAUDE.md files (project-level instructions) + +CLAUDE.md files provide project-specific context and instructions that are automatically read by the Agent SDK when it runs in a directory. They serve as persistent "memory" for your project. + +#### How CLAUDE.md works with the SDK + +**Location and discovery:** + +* **Project-level:** `CLAUDE.md` or `.claude/CLAUDE.md` in your working directory +* **User-level:** `~/.claude/CLAUDE.md` for global instructions across all projects + +**IMPORTANT:** The SDK only reads CLAUDE.md files when you explicitly configure `settingSources` (TypeScript) or `setting_sources` (Python): + +* Include `'project'` to load project-level CLAUDE.md +* Include `'user'` to load user-level CLAUDE.md (`~/.claude/CLAUDE.md`) + +The `claude_code` system prompt preset does NOT automatically load CLAUDE.md - you must also specify setting sources. + +**Content format:** +CLAUDE.md files use plain markdown and can contain: + +* Coding guidelines and standards +* Project-specific context +* Common commands or workflows +* API conventions +* Testing requirements + +#### Example CLAUDE.md + +```markdown theme={null} +# Project Guidelines + +## Code Style + +- Use TypeScript strict mode +- Prefer functional components in React +- Always include JSDoc comments for public APIs + +## Testing + +- Run `npm test` before committing +- Maintain >80% code coverage +- Use jest for unit tests, playwright for E2E + +## Commands + +- Build: `npm run build` +- Dev server: `npm run dev` +- Type check: `npm run typecheck` +``` + +#### Using CLAUDE.md with the SDK + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // IMPORTANT: You must specify settingSources to load CLAUDE.md + // The claude_code preset alone does NOT load CLAUDE.md files + const messages = []; + + for await (const message of query({ + prompt: "Add a new React component for user profiles", + options: { + systemPrompt: { + type: "preset", + preset: "claude_code" // Use Claude Code's system prompt + }, + settingSources: ["project"] // Required to load CLAUDE.md from project + } + })) { + messages.push(message); + } + + // Now Claude has access to your project guidelines from CLAUDE.md + ``` + + ```python Python theme={null} + from claude_agent_sdk import query, ClaudeAgentOptions + + # IMPORTANT: You must specify setting_sources to load CLAUDE.md + # The claude_code preset alone does NOT load CLAUDE.md files + messages = [] + + async for message in query( + prompt="Add a new React component for user profiles", + options=ClaudeAgentOptions( + system_prompt={ + "type": "preset", + "preset": "claude_code", # Use Claude Code's system prompt + }, + setting_sources=["project"], # Required to load CLAUDE.md from project + ), + ): + messages.append(message) + + # Now Claude has access to your project guidelines from CLAUDE.md + ``` + + +#### When to use CLAUDE.md + +**Best for:** + +* **Team-shared context** - Guidelines everyone should follow +* **Project conventions** - Coding standards, file structure, naming patterns +* **Common commands** - Build, test, deploy commands specific to your project +* **Long-term memory** - Context that should persist across all sessions +* **Version-controlled instructions** - Commit to git so the team stays in sync + +**Key characteristics:** + +* ✅ Persistent across all sessions in a project +* ✅ Shared with team via git +* ✅ Automatic discovery (no code changes needed) +* ⚠️ Requires loading settings via `settingSources` + +### Method 2: Output styles (persistent configurations) + +Output styles are saved configurations that modify Claude's system prompt. They're stored as markdown files and can be reused across sessions and projects. + +#### Creating an output style + + + ```typescript TypeScript theme={null} + import { writeFile, mkdir } from "fs/promises"; + import { join } from "path"; + import { homedir } from "os"; + + async function createOutputStyle(name: string, description: string, prompt: string) { + // User-level: ~/.claude/output-styles + // Project-level: .claude/output-styles + const outputStylesDir = join(homedir(), ".claude", "output-styles"); + + await mkdir(outputStylesDir, { recursive: true }); + + const content = `--- + name: ${name} + description: ${description} + --- + + ${prompt}`; + + const filePath = join(outputStylesDir, `${name.toLowerCase().replace(/\s+/g, "-")}.md`); + await writeFile(filePath, content, "utf-8"); + } + + // Example: Create a code review specialist + await createOutputStyle( + "Code Reviewer", + "Thorough code review assistant", + `You are an expert code reviewer. + + For every code submission: + 1. Check for bugs and security issues + 2. Evaluate performance + 3. Suggest improvements + 4. Rate code quality (1-10)` + ); + ``` + + ```python Python theme={null} + from pathlib import Path + + + async def create_output_style(name: str, description: str, prompt: str): + # User-level: ~/.claude/output-styles + # Project-level: .claude/output-styles + output_styles_dir = Path.home() / ".claude" / "output-styles" + + output_styles_dir.mkdir(parents=True, exist_ok=True) + + content = f"""--- + name: {name} + description: {description} + --- + + {prompt}""" + + file_name = name.lower().replace(" ", "-") + ".md" + file_path = output_styles_dir / file_name + file_path.write_text(content, encoding="utf-8") + + + # Example: Create a code review specialist + await create_output_style( + "Code Reviewer", + "Thorough code review assistant", + """You are an expert code reviewer. + + For every code submission: + 1. Check for bugs and security issues + 2. Evaluate performance + 3. Suggest improvements + 4. Rate code quality (1-10)""", + ) + ``` + + +#### Using output styles + +Once created, activate output styles via: + +* **CLI**: `/output-style [style-name]` +* **Settings**: `.claude/settings.local.json` +* **Create new**: `/output-style:new [description]` + +**Note for SDK users:** Output styles are loaded when you include `settingSources: ['user']` or `settingSources: ['project']` (TypeScript) / `setting_sources=["user"]` or `setting_sources=["project"]` (Python) in your options. + +### Method 3: Using `systemPrompt` with append + +You can use the Claude Code preset with an `append` property to add your custom instructions while preserving all built-in functionality. + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + const messages = []; + + for await (const message of query({ + prompt: "Help me write a Python function to calculate fibonacci numbers", + options: { + systemPrompt: { + type: "preset", + preset: "claude_code", + append: "Always include detailed docstrings and type hints in Python code." + } + } + })) { + messages.push(message); + if (message.type === "assistant") { + console.log(message.message.content); + } + } + ``` + + ```python Python theme={null} + from claude_agent_sdk import query, ClaudeAgentOptions + + messages = [] + + async for message in query( + prompt="Help me write a Python function to calculate fibonacci numbers", + options=ClaudeAgentOptions( + system_prompt={ + "type": "preset", + "preset": "claude_code", + "append": "Always include detailed docstrings and type hints in Python code.", + } + ), + ): + messages.append(message) + if message.type == "assistant": + print(message.message.content) + ``` + + +### Method 4: Custom system prompts + +You can provide a custom string as `systemPrompt` to replace the default entirely with your own instructions. + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + const customPrompt = `You are a Python coding specialist. + Follow these guidelines: + - Write clean, well-documented code + - Use type hints for all functions + - Include comprehensive docstrings + - Prefer functional programming patterns when appropriate + - Always explain your code choices`; + + const messages = []; + + for await (const message of query({ + prompt: "Create a data processing pipeline", + options: { + systemPrompt: customPrompt + } + })) { + messages.push(message); + if (message.type === "assistant") { + console.log(message.message.content); + } + } + ``` + + ```python Python theme={null} + from claude_agent_sdk import query, ClaudeAgentOptions + + custom_prompt = """You are a Python coding specialist. + Follow these guidelines: + - Write clean, well-documented code + - Use type hints for all functions + - Include comprehensive docstrings + - Prefer functional programming patterns when appropriate + - Always explain your code choices""" + + messages = [] + + async for message in query( + prompt="Create a data processing pipeline", + options=ClaudeAgentOptions(system_prompt=custom_prompt), + ): + messages.append(message) + if message.type == "assistant": + print(message.message.content) + ``` + + +## Comparison of all four approaches + +| Feature | CLAUDE.md | Output Styles | `systemPrompt` with append | Custom `systemPrompt` | +| ----------------------- | ---------------- | --------------- | -------------------------- | ---------------------- | +| **Persistence** | Per-project file | Saved as files | Session only | Session only | +| **Reusability** | Per-project | Across projects | Code duplication | Code duplication | +| **Management** | On filesystem | CLI + files | In code | In code | +| **Default tools** | Preserved | Preserved | Preserved | Lost (unless included) | +| **Built-in safety** | Maintained | Maintained | Maintained | Must be added | +| **Environment context** | Automatic | Automatic | Automatic | Must be provided | +| **Customization level** | Additions only | Replace default | Additions only | Complete control | +| **Version control** | With project | Yes | With code | With code | +| **Scope** | Project-specific | User or project | Code session | Code session | + +**Note:** "With append" means using `systemPrompt: { type: "preset", preset: "claude_code", append: "..." }` in TypeScript or `system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}` in Python. + +## Use cases and best practices + +### When to use CLAUDE.md + +**Best for:** + +* Project-specific coding standards and conventions +* Documenting project structure and architecture +* Listing common commands (build, test, deploy) +* Team-shared context that should be version controlled +* Instructions that apply to all SDK usage in a project + +**Examples:** + +* "All API endpoints should use async/await patterns" +* "Run `npm run lint:fix` before committing" +* "Database migrations are in the `migrations/` directory" + +**Important:** To load CLAUDE.md files, you must explicitly set `settingSources: ['project']` (TypeScript) or `setting_sources=["project"]` (Python). The `claude_code` system prompt preset does NOT automatically load CLAUDE.md without this setting. + +### When to use output styles + +**Best for:** + +* Persistent behavior changes across sessions +* Team-shared configurations +* Specialized assistants (code reviewer, data scientist, DevOps) +* Complex prompt modifications that need versioning + +**Examples:** + +* Creating a dedicated SQL optimization assistant +* Building a security-focused code reviewer +* Developing a teaching assistant with specific pedagogy + +### When to use `systemPrompt` with append + +**Best for:** + +* Adding specific coding standards or preferences +* Customizing output formatting +* Adding domain-specific knowledge +* Modifying response verbosity +* Enhancing Claude Code's default behavior without losing tool instructions + +### When to use custom `systemPrompt` + +**Best for:** + +* Complete control over Claude's behavior +* Specialized single-session tasks +* Testing new prompt strategies +* Situations where default tools aren't needed +* Building specialized agents with unique behavior + +## Combining approaches + +You can combine these methods for maximum flexibility: + +### Example: Output style with session-specific additions + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Assuming "Code Reviewer" output style is active (via /output-style) + // Add session-specific focus areas + const messages = []; + + for await (const message of query({ + prompt: "Review this authentication module", + options: { + systemPrompt: { + type: "preset", + preset: "claude_code", + append: ` + For this review, prioritize: + - OAuth 2.0 compliance + - Token storage security + - Session management + ` + } + } + })) { + messages.push(message); + } + ``` + + ```python Python theme={null} + from claude_agent_sdk import query, ClaudeAgentOptions + + # Assuming "Code Reviewer" output style is active (via /output-style) + # Add session-specific focus areas + messages = [] + + async for message in query( + prompt="Review this authentication module", + options=ClaudeAgentOptions( + system_prompt={ + "type": "preset", + "preset": "claude_code", + "append": """ + For this review, prioritize: + - OAuth 2.0 compliance + - Token storage security + - Session management + """, + } + ), + ): + messages.append(message) + ``` + + +## See also + +* [Output styles](/en/output-styles) - Complete output styles documentation +* [TypeScript SDK guide](/en/agent-sdk/typescript) - Complete SDK usage guide +* [Configuration guide](/en/settings) - General configuration options diff --git a/content/en/docs/claude-code/agent-sdk/observability.md b/content/en/docs/claude-code/agent-sdk/observability.md new file mode 100644 index 000000000..1c6315160 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/observability.md @@ -0,0 +1,205 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Observability with OpenTelemetry + +> Export traces, metrics, and events from the Agent SDK to your observability backend using OpenTelemetry. + +When you run agents in production, you need visibility into what they did: + +* which tools they called +* how long each model request took +* how many tokens were spent +* where failures occurred + +The Agent SDK can export this data as OpenTelemetry traces, metrics, and log events to any backend that accepts the OpenTelemetry Protocol (OTLP), such as Honeycomb, Datadog, Grafana, Langfuse, or a self-hosted collector. + +This guide explains how the SDK emits telemetry, how to configure the export, and how to tag and filter the data once it reaches your backend. To read token usage and cost directly from the SDK response stream instead of exporting to a backend, see [Track cost and usage](/en/agent-sdk/cost-tracking). + +## How telemetry flows from the SDK + +The Agent SDK runs the Claude Code CLI as a child process and communicates with it over a local pipe. The CLI has OpenTelemetry instrumentation built in: it records spans around each model request and tool execution, emits metrics for token and cost counters, and emits structured log events for prompts and tool results. The SDK does not produce telemetry of its own. Instead, it passes configuration through to the CLI process, and the CLI exports directly to your collector. + +Configuration is passed as environment variables. By default, the child process inherits your application's environment, so you can configure telemetry in either of two places: + +* **Process environment:** set the variables in your shell, container, or orchestrator before your application starts. Every `query()` call picks them up automatically with no code change. This is the recommended approach for production deployments. +* **Per-call options:** set the variables in `ClaudeAgentOptions.env` (Python) or `options.env` (TypeScript). Use this when different agents in the same process need different telemetry settings. In Python, `env` is merged on top of the inherited environment. In TypeScript, `env` replaces the inherited environment entirely, so include `...process.env` in the object you pass. + +The CLI exports three independent OpenTelemetry signals. Each has its own enable switch and its own exporter, so you can turn on only the ones you need. + +| Signal | What it contains | Enable with | +| ---------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------- | +| Metrics | Counters for tokens, cost, sessions, lines of code, and tool decisions | `OTEL_METRICS_EXPORTER` | +| Log events | Structured records for each prompt, API request, API error, and tool result | `OTEL_LOGS_EXPORTER` | +| Traces | Spans for each interaction, model request, tool call, and hook (beta) | `OTEL_TRACES_EXPORTER` plus `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` | + +For the complete list of metric names, event names, and attributes, see the Claude Code [Monitoring](/en/monitoring-usage) reference. The Agent SDK emits the same data because it runs the same CLI. Span names are listed in [Read agent traces](#read-agent-traces) below. + +## Enable telemetry export + +Telemetry is off until you set `CLAUDE_CODE_ENABLE_TELEMETRY=1` and choose at least one exporter. The most common configuration sends all three signals over OTLP HTTP to a collector. + +The following example sets the variables in a dictionary and passes them through `options.env`. The agent runs a single task, and the CLI exports spans, metrics, and events to the collector at `collector.example.com` while the loop consumes the response stream: + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions + + OTEL_ENV = { + "CLAUDE_CODE_ENABLE_TELEMETRY": "1", + # Required for traces, which are in beta. Metrics and log events do not need this. + "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1", + # Choose an exporter per signal. Use otlp for the SDK; see the Note below. + "OTEL_TRACES_EXPORTER": "otlp", + "OTEL_METRICS_EXPORTER": "otlp", + "OTEL_LOGS_EXPORTER": "otlp", + # Standard OTLP transport configuration. + "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf", + "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4318", + "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-token", + } + + + async def main(): + options = ClaudeAgentOptions(env=OTEL_ENV) + async for message in query( + prompt="List the files in this directory", options=options + ): + print(message) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + const otelEnv = { + CLAUDE_CODE_ENABLE_TELEMETRY: "1", + // Required for traces, which are in beta. Metrics and log events do not need this. + CLAUDE_CODE_ENHANCED_TELEMETRY_BETA: "1", + // Choose an exporter per signal. Use otlp for the SDK; see the Note below. + OTEL_TRACES_EXPORTER: "otlp", + OTEL_METRICS_EXPORTER: "otlp", + OTEL_LOGS_EXPORTER: "otlp", + // Standard OTLP transport configuration. + OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf", + OTEL_EXPORTER_OTLP_ENDPOINT: "http://collector.example.com:4318", + OTEL_EXPORTER_OTLP_HEADERS: "Authorization=Bearer your-token", + }; + + for await (const message of query({ + prompt: "List the files in this directory", + // env replaces the inherited environment in TypeScript, so spread + // process.env first to keep PATH, ANTHROPIC_API_KEY, and other variables. + options: { env: { ...process.env, ...otelEnv } }, + })) { + console.log(message); + } + ``` + + +Because the child process inherits your application's environment by default, you can achieve the same result by exporting these variables in a Dockerfile, Kubernetes manifest, or shell profile and omitting `options.env` entirely. + + + The `console` exporter writes telemetry to standard output, which the SDK uses + as its message channel. Do not set `console` as an exporter value when running + through the SDK. To inspect telemetry locally, point + `OTEL_EXPORTER_OTLP_ENDPOINT` at a local collector or an all-in-one Jaeger + container instead. + + +### Flush telemetry from short-lived calls + +The CLI batches telemetry and exports on an interval. It flushes any pending data when the process exits cleanly, so a `query()` call that completes normally does not lose spans. However, if your process is killed before the CLI shuts down, anything still in the batch buffer is lost. Lowering the export intervals reduces that window. + +By default, metrics export every 60 seconds and traces and logs export every 5 seconds. The following example shortens all three intervals so that data reaches the collector while a short task is still running: + + + ```python Python theme={null} + OTEL_ENV = { + # ... exporter configuration from the previous example ... + "OTEL_METRIC_EXPORT_INTERVAL": "1000", + "OTEL_LOGS_EXPORT_INTERVAL": "1000", + "OTEL_TRACES_EXPORT_INTERVAL": "1000", + } + ``` + + ```typescript TypeScript theme={null} + const otelEnv = { + // ... exporter configuration from the previous example ... + OTEL_METRIC_EXPORT_INTERVAL: "1000", + OTEL_LOGS_EXPORT_INTERVAL: "1000", + OTEL_TRACES_EXPORT_INTERVAL: "1000", + }; + ``` + + +## Read agent traces + +Traces give you the most detailed view of an agent run. With `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` set, each step of the agent loop becomes a span you can inspect in your tracing backend: + +* **`claude_code.interaction`:** wraps a single turn of the agent loop, from receiving a prompt to producing a response. +* **`claude_code.llm_request`:** wraps each call to the Claude API, with model name, latency, and token counts as attributes. +* **`claude_code.tool`:** wraps each tool invocation, with child spans for the permission wait (`claude_code.tool.blocked_on_user`) and the execution itself (`claude_code.tool.execution`). +* **`claude_code.hook`:** wraps each [hook](/en/agent-sdk/hooks) execution. + +Every span carries a `session.id` attribute. When you make several `query()` calls against the same [session](/en/agent-sdk/sessions), filter on `session.id` in your backend to see them as one timeline. + + + Tracing is in beta. Span names and attributes may change between releases. See + [Traces (beta)](/en/monitoring-usage#traces-beta) in the Monitoring reference + for the trace exporter configuration variables. + + +## Tag telemetry from your agent + +By default, the CLI reports `service.name` as `claude-code`. If you run several agents, or run the SDK alongside other services that export to the same collector, override the service name and add resource attributes so you can filter by agent in your backend. + +The following example renames the service and attaches deployment metadata. These values are applied as OpenTelemetry resource attributes on every span, metric, and event the agent emits: + + + ```python Python theme={null} + options = ClaudeAgentOptions( + env={ + # ... exporter configuration ... + "OTEL_SERVICE_NAME": "support-triage-agent", + "OTEL_RESOURCE_ATTRIBUTES": "service.version=1.4.0,deployment.environment=production", + }, + ) + ``` + + ```typescript TypeScript theme={null} + const options = { + env: { + ...process.env, + // ... exporter configuration ... + OTEL_SERVICE_NAME: "support-triage-agent", + OTEL_RESOURCE_ATTRIBUTES: + "service.version=1.4.0,deployment.environment=production", + }, + }; + ``` + + +## Control sensitive data in exports + +Telemetry is structural by default. Token counts, durations, model names, and tool names are always recorded, but the content your agent reads and writes is not. Three opt-in variables add content to the exported data: + +| Variable | Adds | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `OTEL_LOG_USER_PROMPTS=1` | Prompt text on `claude_code.user_prompt` events and on the `claude_code.interaction` span | +| `OTEL_LOG_TOOL_DETAILS=1` | Tool input arguments (file paths, shell commands, search patterns) on `claude_code.tool_result` events | +| `OTEL_LOG_TOOL_CONTENT=1` | Full tool input and output bodies as span events on `claude_code.tool`, truncated at 60 KB. Requires [tracing](#read-agent-traces) to be enabled | + +Leave these unset unless your observability pipeline is approved to store the data your agent handles. See [Security and privacy](/en/monitoring-usage#security-and-privacy) in the Monitoring reference for the full list of attributes and redaction behavior. + +## Related documentation + +These guides cover adjacent topics for monitoring and deploying agents: + +* [Track cost and usage](/en/agent-sdk/cost-tracking): read token and cost data from the message stream without an external backend. +* [Hosting the Agent SDK](/en/agent-sdk/hosting): deploy agents in containers where you can set OpenTelemetry variables at the environment level. +* [Monitoring](/en/monitoring-usage): the complete reference for every environment variable, metric, and event the CLI emits. diff --git a/content/en/docs/claude-code/agent-sdk/overview.md b/content/en/docs/claude-code/agent-sdk/overview.md new file mode 100644 index 000000000..1d4acda8e --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/overview.md @@ -0,0 +1,583 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Agent SDK overview + +> Build production AI agents with Claude Code as a library + + + The Claude Code SDK has been renamed to the Claude Agent SDK. If you're migrating from the old SDK, see the [Migration Guide](/en/agent-sdk/migration-guide). + + +Build AI agents that autonomously read files, run commands, search the web, edit code, and more. The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions + + + async def main(): + async for message in query( + prompt="Find and fix the bug in auth.py", + options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]), + ): + print(message) # Claude reads the file, finds the bug, edits it + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Find and fix the bug in auth.py", + options: { allowedTools: ["Read", "Edit", "Bash"] } + })) { + console.log(message); // Claude reads the file, finds the bug, edits it + } + ``` + + +The Agent SDK includes built-in tools for reading files, running commands, and editing code, so your agent can start working immediately without you implementing tool execution. Dive into the quickstart or explore real agents built with the SDK: + + + + Build a bug-fixing agent in minutes + + + + Email assistant, research agent, and more + + + +## Get started + + + + + + ```bash theme={null} + npm install @anthropic-ai/claude-agent-sdk + ``` + + + + ```bash theme={null} + pip install claude-agent-sdk + ``` + + + + + + Get an API key from the [Console](https://platform.claude.com/), then set it as an environment variable: + + ```bash theme={null} + export ANTHROPIC_API_KEY=your-api-key + ``` + + The SDK also supports authentication via third-party API providers: + + * **Amazon Bedrock**: set `CLAUDE_CODE_USE_BEDROCK=1` environment variable and configure AWS credentials + * **Google Vertex AI**: set `CLAUDE_CODE_USE_VERTEX=1` environment variable and configure Google Cloud credentials + * **Microsoft Azure**: set `CLAUDE_CODE_USE_FOUNDRY=1` environment variable and configure Azure credentials + + See the setup guides for [Bedrock](/en/amazon-bedrock), [Vertex AI](/en/google-vertex-ai), or [Azure AI Foundry](/en/microsoft-foundry) for details. + + + Unless previously approved, Anthropic does not allow third party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK. Please use the API key authentication methods described in this document instead. + + + + + This example creates an agent that lists files in your current directory using built-in tools. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions + + + async def main(): + async for message in query( + prompt="What files are in this directory?", + options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]), + ): + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "What files are in this directory?", + options: { allowedTools: ["Bash", "Glob"] } + })) { + if ("result" in message) console.log(message.result); + } + ``` + + + + +**Ready to build?** Follow the [Quickstart](/en/agent-sdk/quickstart) to create an agent that finds and fixes bugs in minutes. + +## Capabilities + +Everything that makes Claude Code powerful is available in the SDK: + + + + Your agent can read files, run commands, and search codebases out of the box. Key tools include: + + | Tool | What it does | + | --------------------------------------------------------------------------- | -------------------------------------------------------------- | + | **Read** | Read any file in the working directory | + | **Write** | Create new files | + | **Edit** | Make precise edits to existing files | + | **Bash** | Run terminal commands, scripts, git operations | + | **Glob** | Find files by pattern (`**/*.ts`, `src/**/*.py`) | + | **Grep** | Search file contents with regex | + | **WebSearch** | Search the web for current information | + | **WebFetch** | Fetch and parse web page content | + | **[AskUserQuestion](/en/agent-sdk/user-input#handle-clarifying-questions)** | Ask the user clarifying questions with multiple choice options | + + This example creates an agent that searches your codebase for TODO comments: + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions + + + async def main(): + async for message in query( + prompt="Find all TODO comments and create a summary", + options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]), + ): + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Find all TODO comments and create a summary", + options: { allowedTools: ["Read", "Glob", "Grep"] } + })) { + if ("result" in message) console.log(message.result); + } + ``` + + + + + Run custom code at key points in the agent lifecycle. SDK hooks use callback functions to validate, log, block, or transform agent behavior. + + **Available hooks:** `PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, and more. + + This example logs all file changes to an audit file: + + + ```python Python theme={null} + import asyncio + from datetime import datetime + from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher + + + async def log_file_change(input_data, tool_use_id, context): + file_path = input_data.get("tool_input", {}).get("file_path", "unknown") + with open("./audit.log", "a") as f: + f.write(f"{datetime.now()}: modified {file_path}\n") + return {} + + + async def main(): + async for message in query( + prompt="Refactor utils.py to improve readability", + options=ClaudeAgentOptions( + permission_mode="acceptEdits", + hooks={ + "PostToolUse": [ + HookMatcher(matcher="Edit|Write", hooks=[log_file_change]) + ] + }, + ), + ): + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk"; + import { appendFile } from "fs/promises"; + + const logFileChange: HookCallback = async (input) => { + const filePath = (input as any).tool_input?.file_path ?? "unknown"; + await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`); + return {}; + }; + + for await (const message of query({ + prompt: "Refactor utils.py to improve readability", + options: { + permissionMode: "acceptEdits", + hooks: { + PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }] + } + } + })) { + if ("result" in message) console.log(message.result); + } + ``` + + + [Learn more about hooks →](/en/agent-sdk/hooks) + + + + Spawn specialized agents to handle focused subtasks. Your main agent delegates work, and subagents report back with results. + + Define custom agents with specialized instructions. Include `Agent` in `allowedTools` since subagents are invoked via the Agent tool: + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition + + + async def main(): + async for message in query( + prompt="Use the code-reviewer agent to review this codebase", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Glob", "Grep", "Agent"], + agents={ + "code-reviewer": AgentDefinition( + description="Expert code reviewer for quality and security reviews.", + prompt="Analyze code quality and suggest improvements.", + tools=["Read", "Glob", "Grep"], + ) + }, + ), + ): + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Use the code-reviewer agent to review this codebase", + options: { + allowedTools: ["Read", "Glob", "Grep", "Agent"], + agents: { + "code-reviewer": { + description: "Expert code reviewer for quality and security reviews.", + prompt: "Analyze code quality and suggest improvements.", + tools: ["Read", "Glob", "Grep"] + } + } + } + })) { + if ("result" in message) console.log(message.result); + } + ``` + + + Messages from within a subagent's context include a `parent_tool_use_id` field, letting you track which messages belong to which subagent execution. + + [Learn more about subagents →](/en/agent-sdk/subagents) + + + + Connect to external systems via the Model Context Protocol: databases, browsers, APIs, and [hundreds more](https://github.com/modelcontextprotocol/servers). + + This example connects the [Playwright MCP server](https://github.com/microsoft/playwright-mcp) to give your agent browser automation capabilities: + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions + + + async def main(): + async for message in query( + prompt="Open example.com and describe what you see", + options=ClaudeAgentOptions( + mcp_servers={ + "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]} + } + ), + ): + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Open example.com and describe what you see", + options: { + mcpServers: { + playwright: { command: "npx", args: ["@playwright/mcp@latest"] } + } + } + })) { + if ("result" in message) console.log(message.result); + } + ``` + + + [Learn more about MCP →](/en/agent-sdk/mcp) + + + + Control exactly which tools your agent can use. Allow safe operations, block dangerous ones, or require approval for sensitive actions. + + + For interactive approval prompts and the `AskUserQuestion` tool, see [Handle approvals and user input](/en/agent-sdk/user-input). + + + This example creates a read-only agent that can analyze but not modify code. `allowed_tools` pre-approves `Read`, `Glob`, and `Grep`. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions + + + async def main(): + async for message in query( + prompt="Review this code for best practices", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Glob", "Grep"], + ), + ): + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Review this code for best practices", + options: { + allowedTools: ["Read", "Glob", "Grep"] + } + })) { + if ("result" in message) console.log(message.result); + } + ``` + + + [Learn more about permissions →](/en/agent-sdk/permissions) + + + + Maintain context across multiple exchanges. Claude remembers files read, analysis done, and conversation history. Resume sessions later, or fork them to explore different approaches. + + This example captures the session ID from the first query, then resumes to continue with full context: + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage + + + async def main(): + session_id = None + + # First query: capture the session ID + async for message in query( + prompt="Read the authentication module", + options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]), + ): + if isinstance(message, SystemMessage) and message.subtype == "init": + session_id = message.data["session_id"] + + # Resume with full context from the first query + async for message in query( + prompt="Now find all places that call it", # "it" = auth module + options=ClaudeAgentOptions(resume=session_id), + ): + if isinstance(message, ResultMessage): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + let sessionId: string | undefined; + + // First query: capture the session ID + for await (const message of query({ + prompt: "Read the authentication module", + options: { allowedTools: ["Read", "Glob"] } + })) { + if (message.type === "system" && message.subtype === "init") { + sessionId = message.session_id; + } + } + + // Resume with full context from the first query + for await (const message of query({ + prompt: "Now find all places that call it", // "it" = auth module + options: { resume: sessionId } + })) { + if ("result" in message) console.log(message.result); + } + ``` + + + [Learn more about sessions →](/en/agent-sdk/sessions) + + + +### Claude Code features + +The SDK also supports Claude Code's filesystem-based configuration. To use these features, set `setting_sources=["project"]` (Python) or `settingSources: ['project']` (TypeScript) in your options. + +| Feature | Description | Location | +| ------------------------------------------------ | ---------------------------------------------------- | ---------------------------------- | +| [Skills](/en/agent-sdk/skills) | Specialized capabilities defined in Markdown | `.claude/skills/*/SKILL.md` | +| [Slash commands](/en/agent-sdk/slash-commands) | Custom commands for common tasks | `.claude/commands/*.md` | +| [Memory](/en/agent-sdk/modifying-system-prompts) | Project context and instructions | `CLAUDE.md` or `.claude/CLAUDE.md` | +| [Plugins](/en/agent-sdk/plugins) | Extend with custom commands, agents, and MCP servers | Programmatic via `plugins` option | + +## Compare the Agent SDK to other Claude tools + +The Claude Platform offers multiple ways to build with Claude. Here's how the Agent SDK fits in: + + + + The [Anthropic Client SDK](https://platform.claude.com/docs/en/api/client-sdks) gives you direct API access: you send prompts and implement tool execution yourself. The **Agent SDK** gives you Claude with built-in tool execution. + + With the Client SDK, you implement a tool loop. With the Agent SDK, Claude handles it: + + + ```python Python theme={null} + # Client SDK: You implement the tool loop + response = client.messages.create(...) + while response.stop_reason == "tool_use": + result = your_tool_executor(response.tool_use) + response = client.messages.create(tool_result=result, **params) + + # Agent SDK: Claude handles tools autonomously + async for message in query(prompt="Fix the bug in auth.py"): + print(message) + ``` + + ```typescript TypeScript theme={null} + // Client SDK: You implement the tool loop + let response = await client.messages.create({ ...params }); + while (response.stop_reason === "tool_use") { + const result = yourToolExecutor(response.tool_use); + response = await client.messages.create({ tool_result: result, ...params }); + } + + // Agent SDK: Claude handles tools autonomously + for await (const message of query({ prompt: "Fix the bug in auth.py" })) { + console.log(message); + } + ``` + + + + + Same capabilities, different interface: + + | Use case | Best choice | + | ----------------------- | ----------- | + | Interactive development | CLI | + | CI/CD pipelines | SDK | + | Custom applications | SDK | + | One-off tasks | CLI | + | Production automation | SDK | + + Many teams use both: CLI for daily development, SDK for production. Workflows translate directly between them. + + + +## Changelog + +View the full changelog for SDK updates, bug fixes, and new features: + +* **TypeScript SDK**: [view CHANGELOG.md](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md) +* **Python SDK**: [view CHANGELOG.md](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md) + +## Reporting bugs + +If you encounter bugs or issues with the Agent SDK: + +* **TypeScript SDK**: [report issues on GitHub](https://github.com/anthropics/claude-agent-sdk-typescript/issues) +* **Python SDK**: [report issues on GitHub](https://github.com/anthropics/claude-agent-sdk-python/issues) + +## Branding guidelines + +For partners integrating the Claude Agent SDK, use of Claude branding is optional. When referencing Claude in your product: + +**Allowed:** + +* "Claude Agent" (preferred for dropdown menus) +* "Claude" (when within a menu already labeled "Agents") +* "{YourAgentName} Powered by Claude" (if you have an existing agent name) + +**Not permitted:** + +* "Claude Code" or "Claude Code Agent" +* Claude Code-branded ASCII art or visual elements that mimic Claude Code + +Your product should maintain its own branding and not appear to be Claude Code or any Anthropic product. For questions about branding compliance, contact the Anthropic [sales team](https://www.anthropic.com/contact-sales). + +## License and terms + +Use of the Claude Agent SDK is governed by [Anthropic's Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms), including when you use it to power products and services that you make available to your own customers and end users, except to the extent a specific component or dependency is covered by a different license as indicated in that component's LICENSE file. + +## Next steps + + + + Build an agent that finds and fixes bugs in minutes + + + + Email assistant, research agent, and more + + + + Full TypeScript API reference and examples + + + + Full Python API reference and examples + + diff --git a/content/en/docs/claude-code/agent-sdk/permissions.md b/content/en/docs/claude-code/agent-sdk/permissions.md new file mode 100644 index 000000000..5c29479be --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/permissions.md @@ -0,0 +1,242 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Configure permissions + +> Control how your agent uses tools with permission modes, hooks, and declarative allow/deny rules. + +The Claude Agent SDK provides permission controls to manage how Claude uses tools. Use permission modes and rules to define what's allowed automatically, and the [`canUseTool` callback](/en/agent-sdk/user-input) to handle everything else at runtime. + + + This page covers permission modes and rules. To build interactive approval flows where users approve or deny tool requests at runtime, see [Handle approvals and user input](/en/agent-sdk/user-input). + + +## How permissions are evaluated + +When Claude requests a tool, the SDK checks permissions in this order: + + + + Run [hooks](/en/agent-sdk/hooks) first, which can allow, deny, or continue to the next step + + + + Check `deny` rules (from `disallowed_tools` and [settings.json](/en/settings#permission-settings)). If a deny rule matches, the tool is blocked, even in `bypassPermissions` mode. + + + + Apply the active [permission mode](#permission-modes). `bypassPermissions` approves everything that reaches this step. `acceptEdits` approves file operations. Other modes fall through. + + + + Check `allow` rules (from `allowed_tools` and settings.json). If a rule matches, the tool is approved. + + + + If not resolved by any of the above, call your [`canUseTool` callback](/en/agent-sdk/user-input) for a decision. In `dontAsk` mode, this step is skipped and the tool is denied. + + + +Permission evaluation flow diagram + +This page focuses on **allow and deny rules** and **permission modes**. For the other steps: + +* **Hooks:** run custom code to allow, deny, or modify tool requests. See [Control execution with hooks](/en/agent-sdk/hooks). +* **canUseTool callback:** prompt users for approval at runtime. See [Handle approvals and user input](/en/agent-sdk/user-input). + +## Allow and deny rules + +`allowed_tools` and `disallowed_tools` (TypeScript: `allowedTools` / `disallowedTools`) add entries to the allow and deny rule lists in the evaluation flow above. They control whether a tool call is approved, not whether the tool is available to Claude. + +| Option | Effect | +| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- | +| `allowed_tools=["Read", "Grep"]` | `Read` and `Grep` are auto-approved. Tools not listed here still exist and fall through to the permission mode and `canUseTool`. | +| `disallowed_tools=["Bash"]` | `Bash` is always denied. Deny rules are checked first and hold in every permission mode, including `bypassPermissions`. | + +For a locked-down agent, pair `allowedTools` with `permissionMode: "dontAsk"`. Listed tools are approved; anything else is denied outright instead of prompting: + +```typescript theme={null} +const options = { + allowedTools: ["Read", "Glob", "Grep"], + permissionMode: "dontAsk" +}; +``` + + + **`allowed_tools` does not constrain `bypassPermissions`.** `allowed_tools` only pre-approves the tools you list. Unlisted tools are not matched by any allow rule and fall through to the permission mode, where `bypassPermissions` approves them. Setting `allowed_tools=["Read"]` alongside `permission_mode="bypassPermissions"` still approves every tool, including `Bash`, `Write`, and `Edit`. If you need `bypassPermissions` but want specific tools blocked, use `disallowed_tools`. + + +You can also configure allow, deny, and ask rules declaratively in `.claude/settings.json`. The SDK does not load filesystem settings by default, so you must set `setting_sources=["project"]` (TypeScript: `settingSources: ["project"]`) in your options for these rules to apply. See [Permission settings](/en/settings#permission-settings) for the rule syntax. + +## Permission modes + +Permission modes provide global control over how Claude uses tools. You can set the permission mode when calling `query()` or change it dynamically during streaming sessions. + +### Available modes + +The SDK supports these permission modes: + +| Mode | Description | Tool behavior | +| :----------------------- | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | +| `default` | Standard permission behavior | No auto-approvals; unmatched tools trigger your `canUseTool` callback | +| `dontAsk` | Deny instead of prompting | Anything not pre-approved by `allowed_tools` or rules is denied; `canUseTool` is never called | +| `acceptEdits` | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) are automatically approved | +| `bypassPermissions` | Bypass all permission checks | All tools run without permission prompts (use with caution) | +| `plan` | Planning mode | No tool execution; Claude plans without making changes | +| `auto` (TypeScript only) | Model-classified approvals | A model classifier approves or denies each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability | + + + **Subagent inheritance:** When using `bypassPermissions`, all subagents inherit this mode and it cannot be overridden. Subagents may have different system prompts and less constrained behavior than your main agent. Enabling `bypassPermissions` grants them full, autonomous system access without any approval prompts. + + +### Set permission mode + +You can set the permission mode once when starting a query, or change it dynamically while the session is active. + + + + Pass `permission_mode` (Python) or `permissionMode` (TypeScript) when creating a query. This mode applies for the entire session unless changed dynamically. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions + + + async def main(): + async for message in query( + prompt="Help me refactor this code", + options=ClaudeAgentOptions( + permission_mode="default", # Set the mode here + ), + ): + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + async function main() { + for await (const message of query({ + prompt: "Help me refactor this code", + options: { + permissionMode: "default" // Set the mode here + } + })) { + if ("result" in message) { + console.log(message.result); + } + } + } + + main(); + ``` + + + + + Call `set_permission_mode()` (Python) or `setPermissionMode()` (TypeScript) to change the mode mid-session. The new mode takes effect immediately for all subsequent tool requests. This lets you start restrictive and loosen permissions as trust builds, for example switching to `acceptEdits` after reviewing Claude's initial approach. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions + + + async def main(): + q = query( + prompt="Help me refactor this code", + options=ClaudeAgentOptions( + permission_mode="default", # Start in default mode + ), + ) + + # Change mode dynamically mid-session + await q.set_permission_mode("acceptEdits") + + # Process messages with the new permission mode + async for message in q: + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + async function main() { + const q = query({ + prompt: "Help me refactor this code", + options: { + permissionMode: "default" // Start in default mode + } + }); + + // Change mode dynamically mid-session + await q.setPermissionMode("acceptEdits"); + + // Process messages with the new permission mode + for await (const message of q) { + if ("result" in message) { + console.log(message.result); + } + } + } + + main(); + ``` + + + + +### Mode details + +#### Accept edits mode (`acceptEdits`) + +Auto-approves file operations so Claude can edit code without prompting. Other tools (like Bash commands that aren't filesystem operations) still require normal permissions. + +**Auto-approved operations:** + +* File edits (Edit, Write tools) +* Filesystem commands: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed` + +Both apply only to paths inside the working directory or `additionalDirectories`. Paths outside that scope and writes to protected paths still prompt. + +**Use when:** you trust Claude's edits and want faster iteration, such as during prototyping or when working in an isolated directory. + +#### Don't ask mode (`dontAsk`) + +Converts any permission prompt into a denial. Tools pre-approved by `allowed_tools`, `settings.json` allow rules, or a hook run as normal. Everything else is denied without calling `canUseTool`. + +**Use when:** you want a fixed, explicit tool surface for a headless agent and prefer a hard deny over silent reliance on `canUseTool` being absent. + +#### Bypass permissions mode (`bypassPermissions`) + +Auto-approves all tool uses without prompts. Hooks still execute and can block operations if needed. + + + Use with extreme caution. Claude has full system access in this mode. Only use in controlled environments where you trust all possible operations. + + `allowed_tools` does not constrain this mode. Every tool is approved, not just the ones you listed. Deny rules (`disallowed_tools`), explicit `ask` rules, and hooks are evaluated before the mode check and can still block a tool. + + +#### Plan mode (`plan`) + +Prevents tool execution entirely. Claude can analyze code and create plans but cannot make changes. Claude may use `AskUserQuestion` to clarify requirements before finalizing the plan. See [Handle approvals and user input](/en/agent-sdk/user-input#handle-clarifying-questions) for handling these prompts. + +**Use when:** you want Claude to propose changes without executing them, such as during code review or when you need to approve changes before they're made. + +## Related resources + +For the other steps in the permission evaluation flow: + +* [Handle approvals and user input](/en/agent-sdk/user-input): interactive approval prompts and clarifying questions +* [Hooks guide](/en/agent-sdk/hooks): run custom code at key points in the agent lifecycle +* [Permission rules](/en/settings#permission-settings): declarative allow/deny rules in `settings.json` diff --git a/content/en/docs/claude-code/agent-sdk/plugins.md b/content/en/docs/claude-code/agent-sdk/plugins.md new file mode 100644 index 000000000..bf77cc520 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/plugins.md @@ -0,0 +1,342 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Plugins in the SDK + +> Load custom plugins to extend Claude Code with commands, agents, skills, and hooks through the Agent SDK + +Plugins allow you to extend Claude Code with custom functionality that can be shared across projects. Through the Agent SDK, you can programmatically load plugins from local directories to add custom slash commands, agents, skills, hooks, and MCP servers to your agent sessions. + +## What are plugins? + +Plugins are packages of Claude Code extensions that can include: + +* **Skills**: Model-invoked capabilities that Claude uses autonomously (can also be invoked with `/skill-name`) +* **Agents**: Specialized subagents for specific tasks +* **Hooks**: Event handlers that respond to tool use and other events +* **MCP servers**: External tool integrations via Model Context Protocol + + + The `commands/` directory is a legacy format. Use `skills/` for new plugins. Claude Code continues to support both formats for backward compatibility. + + +For complete information on plugin structure and how to create plugins, see [Plugins](/en/plugins). + +## Loading plugins + +Load plugins by providing their local file system paths in your options configuration. The SDK supports loading multiple plugins from different locations. + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Hello", + options: { + plugins: [ + { type: "local", path: "./my-plugin" }, + { type: "local", path: "/absolute/path/to/another-plugin" } + ] + } + })) { + // Plugin commands, agents, and other features are now available + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query + + + async def main(): + async for message in query( + prompt="Hello", + options={ + "plugins": [ + {"type": "local", "path": "./my-plugin"}, + {"type": "local", "path": "/absolute/path/to/another-plugin"}, + ] + }, + ): + # Plugin commands, agents, and other features are now available + pass + + + asyncio.run(main()) + ``` + + +### Path specifications + +Plugin paths can be: + +* **Relative paths**: Resolved relative to your current working directory (for example, `"./plugins/my-plugin"`) +* **Absolute paths**: Full file system paths (for example, `"/home/user/plugins/my-plugin"`) + + + The path should point to the plugin's root directory (the directory containing `.claude-plugin/plugin.json`). + + +## Verifying plugin installation + +When plugins load successfully, they appear in the system initialization message. You can verify that your plugins are available: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Hello", + options: { + plugins: [{ type: "local", path: "./my-plugin" }] + } + })) { + if (message.type === "system" && message.subtype === "init") { + // Check loaded plugins + console.log("Plugins:", message.plugins); + // Example: [{ name: "my-plugin", path: "./my-plugin" }] + + // Check available commands from plugins + console.log("Commands:", message.slash_commands); + // Example: ["/help", "/compact", "my-plugin:custom-command"] + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query + + + async def main(): + async for message in query( + prompt="Hello", options={"plugins": [{"type": "local", "path": "./my-plugin"}]} + ): + if message.type == "system" and message.subtype == "init": + # Check loaded plugins + print("Plugins:", message.data.get("plugins")) + # Example: [{"name": "my-plugin", "path": "./my-plugin"}] + + # Check available commands from plugins + print("Commands:", message.data.get("slash_commands")) + # Example: ["/help", "/compact", "my-plugin:custom-command"] + + + asyncio.run(main()) + ``` + + +## Using plugin skills + +Skills from plugins are automatically namespaced with the plugin name to avoid conflicts. When invoked as slash commands, the format is `plugin-name:skill-name`. + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Load a plugin with a custom /greet skill + for await (const message of query({ + prompt: "/my-plugin:greet", // Use plugin skill with namespace + options: { + plugins: [{ type: "local", path: "./my-plugin" }] + } + })) { + // Claude executes the custom greeting skill from the plugin + if (message.type === "assistant") { + console.log(message.message.content); + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, AssistantMessage, TextBlock + + + async def main(): + # Load a plugin with a custom /greet skill + async for message in query( + prompt="/demo-plugin:greet", # Use plugin skill with namespace + options={"plugins": [{"type": "local", "path": "./plugins/demo-plugin"}]}, + ): + # Claude executes the custom greeting skill from the plugin + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(f"Claude: {block.text}") + + + asyncio.run(main()) + ``` + + + + If you installed a plugin via the CLI (for example, `/plugin install my-plugin@marketplace`), you can still use it in the SDK by providing its installation path. Check `~/.claude/plugins/` for CLI-installed plugins. + + +## Complete example + +Here's a full example demonstrating plugin loading and usage: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + import * as path from "path"; + + async function runWithPlugin() { + const pluginPath = path.join(__dirname, "plugins", "my-plugin"); + + console.log("Loading plugin from:", pluginPath); + + for await (const message of query({ + prompt: "What custom commands do you have available?", + options: { + plugins: [{ type: "local", path: pluginPath }], + maxTurns: 3 + } + })) { + if (message.type === "system" && message.subtype === "init") { + console.log("Loaded plugins:", message.plugins); + console.log("Available commands:", message.slash_commands); + } + + if (message.type === "assistant") { + console.log("Assistant:", message.message.content); + } + } + } + + runWithPlugin().catch(console.error); + ``` + + ```python Python theme={null} + #!/usr/bin/env python3 + """Example demonstrating how to use plugins with the Agent SDK.""" + + from pathlib import Path + import anyio + from claude_agent_sdk import ( + AssistantMessage, + ClaudeAgentOptions, + TextBlock, + query, + ) + + + async def run_with_plugin(): + """Example using a custom plugin.""" + plugin_path = Path(__file__).parent / "plugins" / "demo-plugin" + + print(f"Loading plugin from: {plugin_path}") + + options = ClaudeAgentOptions( + plugins=[{"type": "local", "path": str(plugin_path)}], + max_turns=3, + ) + + async for message in query( + prompt="What custom commands do you have available?", options=options + ): + if message.type == "system" and message.subtype == "init": + print(f"Loaded plugins: {message.data.get('plugins')}") + print(f"Available commands: {message.data.get('slash_commands')}") + + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(f"Assistant: {block.text}") + + + if __name__ == "__main__": + anyio.run(run_with_plugin) + ``` + + +## Plugin structure reference + +A plugin directory must contain a `.claude-plugin/plugin.json` manifest file. It can optionally include: + +```text theme={null} +my-plugin/ +├── .claude-plugin/ +│ └── plugin.json # Required: plugin manifest +├── skills/ # Agent Skills (invoked autonomously or via /skill-name) +│ └── my-skill/ +│ └── SKILL.md +├── commands/ # Legacy: use skills/ instead +│ └── custom-cmd.md +├── agents/ # Custom agents +│ └── specialist.md +├── hooks/ # Event handlers +│ └── hooks.json +└── .mcp.json # MCP server definitions +``` + +For detailed information on creating plugins, see: + +* [Plugins](/en/plugins) - Complete plugin development guide +* [Plugins reference](/en/plugins-reference) - Technical specifications and schemas + +## Common use cases + +### Development and testing + +Load plugins during development without installing them globally: + +```typescript theme={null} +plugins: [{ type: "local", path: "./dev-plugins/my-plugin" }]; +``` + +### Project-specific extensions + +Include plugins in your project repository for team-wide consistency: + +```typescript theme={null} +plugins: [{ type: "local", path: "./project-plugins/team-workflows" }]; +``` + +### Multiple plugin sources + +Combine plugins from different locations: + +```typescript theme={null} +plugins: [ + { type: "local", path: "./local-plugin" }, + { type: "local", path: "~/.claude/custom-plugins/shared-plugin" } +]; +``` + +## Troubleshooting + +### Plugin not loading + +If your plugin doesn't appear in the init message: + +1. **Check the path**: Ensure the path points to the plugin root directory (containing `.claude-plugin/`) +2. **Validate plugin.json**: Ensure your manifest file has valid JSON syntax +3. **Check file permissions**: Ensure the plugin directory is readable + +### Skills not appearing + +If plugin skills don't work: + +1. **Use the namespace**: Plugin skills require the `plugin-name:skill-name` format when invoked as slash commands +2. **Check init message**: Verify the skill appears in `slash_commands` with the correct namespace +3. **Validate skill files**: Ensure each skill has a `SKILL.md` file in its own subdirectory under `skills/` (for example, `skills/my-skill/SKILL.md`) + +### Path resolution issues + +If relative paths don't work: + +1. **Check working directory**: Relative paths are resolved from your current working directory +2. **Use absolute paths**: For reliability, consider using absolute paths +3. **Normalize paths**: Use path utilities to construct paths correctly + +## See also + +* [Plugins](/en/plugins) - Complete plugin development guide +* [Plugins reference](/en/plugins-reference) - Technical specifications +* [Slash Commands](/en/agent-sdk/slash-commands) - Using slash commands in the SDK +* [Subagents](/en/agent-sdk/subagents) - Working with specialized agents +* [Skills](/en/agent-sdk/skills) - Using Agent Skills diff --git a/content/en/docs/claude-code/agent-sdk/python.md b/content/en/docs/claude-code/agent-sdk/python.md new file mode 100644 index 000000000..312ef1fd8 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/python.md @@ -0,0 +1,3207 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Agent SDK reference - Python + +> Complete API reference for the Python Agent SDK, including all functions, types, and classes. + +## Installation + +```bash theme={null} +pip install claude-agent-sdk +``` + +## Choosing between `query()` and `ClaudeSDKClient` + +The Python SDK provides two ways to interact with Claude Code: + +### Quick comparison + +| Feature | `query()` | `ClaudeSDKClient` | +| :------------------ | :---------------------------- | :--------------------------------- | +| **Session** | Creates new session each time | Reuses same session | +| **Conversation** | Single exchange | Multiple exchanges in same context | +| **Connection** | Managed automatically | Manual control | +| **Streaming Input** | ✅ Supported | ✅ Supported | +| **Interrupts** | ❌ Not supported | ✅ Supported | +| **Hooks** | ✅ Supported | ✅ Supported | +| **Custom Tools** | ✅ Supported | ✅ Supported | +| **Continue Chat** | ❌ New session each time | ✅ Maintains conversation | +| **Use Case** | One-off tasks | Continuous conversations | + +### When to use `query()` (new session each time) + +**Best for:** + +* One-off questions where you don't need conversation history +* Independent tasks that don't require context from previous exchanges +* Simple automation scripts +* When you want a fresh start each time + +### When to use `ClaudeSDKClient` (continuous conversation) + +**Best for:** + +* **Continuing conversations** - When you need Claude to remember context +* **Follow-up questions** - Building on previous responses +* **Interactive applications** - Chat interfaces, REPLs +* **Response-driven logic** - When next action depends on Claude's response +* **Session control** - Managing conversation lifecycle explicitly + +## Functions + +### `query()` + +Creates a new session for each interaction with Claude Code. Returns an async iterator that yields messages as they arrive. Each call to `query()` starts fresh with no memory of previous interactions. + +```python theme={null} +async def query( + *, + prompt: str | AsyncIterable[dict[str, Any]], + options: ClaudeAgentOptions | None = None, + transport: Transport | None = None +) -> AsyncIterator[Message] +``` + +#### Parameters + +| Parameter | Type | Description | +| :---------- | :--------------------------- | :------------------------------------------------------------------------- | +| `prompt` | `str \| AsyncIterable[dict]` | The input prompt as a string or async iterable for streaming mode | +| `options` | `ClaudeAgentOptions \| None` | Optional configuration object (defaults to `ClaudeAgentOptions()` if None) | +| `transport` | `Transport \| None` | Optional custom transport for communicating with the CLI process | + +#### Returns + +Returns an `AsyncIterator[Message]` that yields messages from the conversation. + +#### Example - With options + +```python theme={null} +import asyncio +from claude_agent_sdk import query, ClaudeAgentOptions + + +async def main(): + options = ClaudeAgentOptions( + system_prompt="You are an expert Python developer", + permission_mode="acceptEdits", + cwd="/home/user/project", + ) + + async for message in query(prompt="Create a Python web server", options=options): + print(message) + + +asyncio.run(main()) +``` + +### `tool()` + +Decorator for defining MCP tools with type safety. + +```python theme={null} +def tool( + name: str, + description: str, + input_schema: type | dict[str, Any], + annotations: ToolAnnotations | None = None +) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]] +``` + +#### Parameters + +| Parameter | Type | Description | +| :------------- | :----------------------------------------------- | :------------------------------------------------------------------ | +| `name` | `str` | Unique identifier for the tool | +| `description` | `str` | Human-readable description of what the tool does | +| `input_schema` | `type \| dict[str, Any]` | Schema defining the tool's input parameters (see below) | +| `annotations` | [`ToolAnnotations`](#tool-annotations)` \| None` | Optional MCP tool annotations providing behavioral hints to clients | + +#### Input schema options + +1. **Simple type mapping** (recommended): + + ```python theme={null} + {"text": str, "count": int, "enabled": bool} + ``` + +2. **JSON Schema format** (for complex validation): + ```python theme={null} + { + "type": "object", + "properties": { + "text": {"type": "string"}, + "count": {"type": "integer", "minimum": 0}, + }, + "required": ["text"], + } + ``` + +#### Returns + +A decorator function that wraps the tool implementation and returns an `SdkMcpTool` instance. + +#### Example + +```python theme={null} +from claude_agent_sdk import tool +from typing import Any + + +@tool("greet", "Greet a user", {"name": str}) +async def greet(args: dict[str, Any]) -> dict[str, Any]: + return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]} +``` + +#### `ToolAnnotations` + +Re-exported from `mcp.types` (also available as `from claude_agent_sdk import ToolAnnotations`). All fields are optional hints; clients should not rely on them for security decisions. + +| Field | Type | Default | Description | +| :---------------- | :------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------- | +| `title` | `str \| None` | `None` | Human-readable title for the tool | +| `readOnlyHint` | `bool \| None` | `False` | If `True`, the tool does not modify its environment | +| `destructiveHint` | `bool \| None` | `True` | If `True`, the tool may perform destructive updates (only meaningful when `readOnlyHint` is `False`) | +| `idempotentHint` | `bool \| None` | `False` | If `True`, repeated calls with the same arguments have no additional effect (only meaningful when `readOnlyHint` is `False`) | +| `openWorldHint` | `bool \| None` | `True` | If `True`, the tool interacts with external entities (for example, web search). If `False`, the tool's domain is closed (for example, a memory tool) | + +```python theme={null} +from claude_agent_sdk import tool, ToolAnnotations +from typing import Any + + +@tool( + "search", + "Search the web", + {"query": str}, + annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True), +) +async def search(args: dict[str, Any]) -> dict[str, Any]: + return {"content": [{"type": "text", "text": f"Results for: {args['query']}"}]} +``` + +### `create_sdk_mcp_server()` + +Create an in-process MCP server that runs within your Python application. + +```python theme={null} +def create_sdk_mcp_server( + name: str, + version: str = "1.0.0", + tools: list[SdkMcpTool[Any]] | None = None +) -> McpSdkServerConfig +``` + +#### Parameters + +| Parameter | Type | Default | Description | +| :-------- | :------------------------------ | :-------- | :---------------------------------------------------- | +| `name` | `str` | - | Unique identifier for the server | +| `version` | `str` | `"1.0.0"` | Server version string | +| `tools` | `list[SdkMcpTool[Any]] \| None` | `None` | List of tool functions created with `@tool` decorator | + +#### Returns + +Returns an `McpSdkServerConfig` object that can be passed to `ClaudeAgentOptions.mcp_servers`. + +#### Example + +```python theme={null} +from claude_agent_sdk import tool, create_sdk_mcp_server + + +@tool("add", "Add two numbers", {"a": float, "b": float}) +async def add(args): + return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]} + + +@tool("multiply", "Multiply two numbers", {"a": float, "b": float}) +async def multiply(args): + return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]} + + +calculator = create_sdk_mcp_server( + name="calculator", + version="2.0.0", + tools=[add, multiply], # Pass decorated functions +) + +# Use with Claude +options = ClaudeAgentOptions( + mcp_servers={"calc": calculator}, + allowed_tools=["mcp__calc__add", "mcp__calc__multiply"], +) +``` + +### `list_sessions()` + +Lists past sessions with metadata. Filter by project directory or list sessions across all projects. Synchronous; returns immediately. + +```python theme={null} +def list_sessions( + directory: str | None = None, + limit: int | None = None, + include_worktrees: bool = True +) -> list[SDKSessionInfo] +``` + +#### Parameters + +| Parameter | Type | Default | Description | +| :------------------ | :------------ | :------ | :------------------------------------------------------------------------------------ | +| `directory` | `str \| None` | `None` | Directory to list sessions for. When omitted, returns sessions across all projects | +| `limit` | `int \| None` | `None` | Maximum number of sessions to return | +| `include_worktrees` | `bool` | `True` | When `directory` is inside a git repository, include sessions from all worktree paths | + +#### Return type: `SDKSessionInfo` + +| Property | Type | Description | +| :-------------- | :------------ | :------------------------------------------------------------------- | +| `session_id` | `str` | Unique session identifier | +| `summary` | `str` | Display title: custom title, auto-generated summary, or first prompt | +| `last_modified` | `int` | Last modified time in milliseconds since epoch | +| `file_size` | `int \| None` | Session file size in bytes (`None` for remote storage backends) | +| `custom_title` | `str \| None` | User-set session title | +| `first_prompt` | `str \| None` | First meaningful user prompt in the session | +| `git_branch` | `str \| None` | Git branch at the end of the session | +| `cwd` | `str \| None` | Working directory for the session | +| `tag` | `str \| None` | User-set session tag (see [`tag_session()`](#tag-session)) | +| `created_at` | `int \| None` | Session creation time in milliseconds since epoch | + +#### Example + +Print the 10 most recent sessions for a project. Results are sorted by `last_modified` descending, so the first item is the newest. Omit `directory` to search across all projects. + +```python theme={null} +from claude_agent_sdk import list_sessions + +for session in list_sessions(directory="/path/to/project", limit=10): + print(f"{session.summary} ({session.session_id})") +``` + +### `get_session_messages()` + +Retrieves messages from a past session. Synchronous; returns immediately. + +```python theme={null} +def get_session_messages( + session_id: str, + directory: str | None = None, + limit: int | None = None, + offset: int = 0 +) -> list[SessionMessage] +``` + +#### Parameters + +| Parameter | Type | Default | Description | +| :----------- | :------------ | :------- | :---------------------------------------------------------------- | +| `session_id` | `str` | required | The session ID to retrieve messages for | +| `directory` | `str \| None` | `None` | Project directory to look in. When omitted, searches all projects | +| `limit` | `int \| None` | `None` | Maximum number of messages to return | +| `offset` | `int` | `0` | Number of messages to skip from the start | + +#### Return type: `SessionMessage` + +| Property | Type | Description | +| :------------------- | :----------------------------- | :------------------------ | +| `type` | `Literal["user", "assistant"]` | Message role | +| `uuid` | `str` | Unique message identifier | +| `session_id` | `str` | Session identifier | +| `message` | `Any` | Raw message content | +| `parent_tool_use_id` | `None` | Reserved for future use | + +#### Example + +```python theme={null} +from claude_agent_sdk import list_sessions, get_session_messages + +sessions = list_sessions(limit=1) +if sessions: + messages = get_session_messages(sessions[0].session_id) + for msg in messages: + print(f"[{msg.type}] {msg.uuid}") +``` + +### `get_session_info()` + +Reads metadata for a single session by ID without scanning the full project directory. Synchronous; returns immediately. + +```python theme={null} +def get_session_info( + session_id: str, + directory: str | None = None, +) -> SDKSessionInfo | None +``` + +#### Parameters + +| Parameter | Type | Default | Description | +| :----------- | :------------ | :------- | :--------------------------------------------------------------------- | +| `session_id` | `str` | required | UUID of the session to look up | +| `directory` | `str \| None` | `None` | Project directory path. When omitted, searches all project directories | + +Returns [`SDKSessionInfo`](#return-type-sdk-session-info), or `None` if the session is not found. + +#### Example + +Look up a single session's metadata without scanning the project directory. Useful when you already have a session ID from a previous run. + +```python theme={null} +from claude_agent_sdk import get_session_info + +info = get_session_info("550e8400-e29b-41d4-a716-446655440000") +if info: + print(f"{info.summary} (branch: {info.git_branch}, tag: {info.tag})") +``` + +### `rename_session()` + +Renames a session by appending a custom-title entry. Repeated calls are safe; the most recent title wins. Synchronous. + +```python theme={null} +def rename_session( + session_id: str, + title: str, + directory: str | None = None, +) -> None +``` + +#### Parameters + +| Parameter | Type | Default | Description | +| :----------- | :------------ | :------- | :--------------------------------------------------------------------- | +| `session_id` | `str` | required | UUID of the session to rename | +| `title` | `str` | required | New title. Must be non-empty after stripping whitespace | +| `directory` | `str \| None` | `None` | Project directory path. When omitted, searches all project directories | + +Raises `ValueError` if `session_id` is not a valid UUID or `title` is empty; `FileNotFoundError` if the session cannot be found. + +#### Example + +Rename the most recent session so it's easier to find later. The new title appears in [`SDKSessionInfo.custom_title`](#return-type-sdk-session-info) on subsequent reads. + +```python theme={null} +from claude_agent_sdk import list_sessions, rename_session + +sessions = list_sessions(directory="/path/to/project", limit=1) +if sessions: + rename_session(sessions[0].session_id, "Refactor auth module") +``` + +### `tag_session()` + +Tags a session. Pass `None` to clear the tag. Repeated calls are safe; the most recent tag wins. Synchronous. + +```python theme={null} +def tag_session( + session_id: str, + tag: str | None, + directory: str | None = None, +) -> None +``` + +#### Parameters + +| Parameter | Type | Default | Description | +| :----------- | :------------ | :------- | :--------------------------------------------------------------------- | +| `session_id` | `str` | required | UUID of the session to tag | +| `tag` | `str \| None` | required | Tag string, or `None` to clear. Unicode-sanitized before storing | +| `directory` | `str \| None` | `None` | Project directory path. When omitted, searches all project directories | + +Raises `ValueError` if `session_id` is not a valid UUID or `tag` is empty after sanitization; `FileNotFoundError` if the session cannot be found. + +#### Example + +Tag a session, then filter by that tag on a later read. Pass `None` to clear an existing tag. + +```python theme={null} +from claude_agent_sdk import list_sessions, tag_session + +# Tag a session +tag_session("550e8400-e29b-41d4-a716-446655440000", "needs-review") + +# Later: find all sessions with that tag +for session in list_sessions(directory="/path/to/project"): + if session.tag == "needs-review": + print(session.summary) +``` + +## Classes + +### `ClaudeSDKClient` + +**Maintains a conversation session across multiple exchanges.** This is the Python equivalent of how the TypeScript SDK's `query()` function works internally - it creates a client object that can continue conversations. + +#### Key Features + +* **Session continuity**: Maintains conversation context across multiple `query()` calls +* **Same conversation**: The session retains previous messages +* **Interrupt support**: Can stop execution mid-task +* **Explicit lifecycle**: You control when the session starts and ends +* **Response-driven flow**: Can react to responses and send follow-ups +* **Custom tools and hooks**: Supports custom tools (created with `@tool` decorator) and hooks + +```python theme={null} +class ClaudeSDKClient: + def __init__(self, options: ClaudeAgentOptions | None = None, transport: Transport | None = None) + async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None + async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None + async def receive_messages(self) -> AsyncIterator[Message] + async def receive_response(self) -> AsyncIterator[Message] + async def interrupt(self) -> None + async def set_permission_mode(self, mode: str) -> None + async def set_model(self, model: str | None = None) -> None + async def rewind_files(self, user_message_id: str) -> None + async def get_mcp_status(self) -> McpStatusResponse + async def reconnect_mcp_server(self, server_name: str) -> None + async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None + async def stop_task(self, task_id: str) -> None + async def get_server_info(self) -> dict[str, Any] | None + async def disconnect(self) -> None +``` + +#### Methods + +| Method | Description | +| :---------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `__init__(options)` | Initialize the client with optional configuration | +| `connect(prompt)` | Connect to Claude with an optional initial prompt or message stream | +| `query(prompt, session_id)` | Send a new request in streaming mode | +| `receive_messages()` | Receive all messages from Claude as an async iterator | +| `receive_response()` | Receive messages until and including a ResultMessage | +| `interrupt()` | Send interrupt signal (only works in streaming mode) | +| `set_permission_mode(mode)` | Change the permission mode for the current session | +| `set_model(model)` | Change the model for the current session. Pass `None` to reset to default | +| `rewind_files(user_message_id)` | Restore files to their state at the specified user message. Requires `enable_file_checkpointing=True`. See [File checkpointing](/en/agent-sdk/file-checkpointing) | +| `get_mcp_status()` | Get the status of all configured MCP servers. Returns [`McpStatusResponse`](#mcp-status-response) | +| `reconnect_mcp_server(server_name)` | Retry connecting to an MCP server that failed or was disconnected | +| `toggle_mcp_server(server_name, enabled)` | Enable or disable an MCP server mid-session. Disabling removes its tools | +| `stop_task(task_id)` | Stop a running background task. A [`TaskNotificationMessage`](#task-notification-message) with status `"stopped"` follows in the message stream | +| `get_server_info()` | Get server information including session ID and capabilities | +| `disconnect()` | Disconnect from Claude | + +#### Context Manager Support + +The client can be used as an async context manager for automatic connection management: + +```python theme={null} +async with ClaudeSDKClient() as client: + await client.query("Hello Claude") + async for message in client.receive_response(): + print(message) +``` + +> **Important:** When iterating over messages, avoid using `break` to exit early as this can cause asyncio cleanup issues. Instead, let the iteration complete naturally or use flags to track when you've found what you need. + +#### Example - Continuing a conversation + +```python theme={null} +import asyncio +from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage + + +async def main(): + async with ClaudeSDKClient() as client: + # First question + await client.query("What's the capital of France?") + + # Process response + async for message in client.receive_response(): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(f"Claude: {block.text}") + + # Follow-up question - the session retains the previous context + await client.query("What's the population of that city?") + + async for message in client.receive_response(): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(f"Claude: {block.text}") + + # Another follow-up - still in the same conversation + await client.query("What are some famous landmarks there?") + + async for message in client.receive_response(): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(f"Claude: {block.text}") + + +asyncio.run(main()) +``` + +#### Example - Streaming input with ClaudeSDKClient + +```python theme={null} +import asyncio +from claude_agent_sdk import ClaudeSDKClient + + +async def message_stream(): + """Generate messages dynamically.""" + yield { + "type": "user", + "message": {"role": "user", "content": "Analyze the following data:"}, + } + await asyncio.sleep(0.5) + yield { + "type": "user", + "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"}, + } + await asyncio.sleep(0.5) + yield { + "type": "user", + "message": {"role": "user", "content": "What patterns do you see?"}, + } + + +async def main(): + async with ClaudeSDKClient() as client: + # Stream input to Claude + await client.query(message_stream()) + + # Process response + async for message in client.receive_response(): + print(message) + + # Follow-up in same session + await client.query("Should we be concerned about these readings?") + + async for message in client.receive_response(): + print(message) + + +asyncio.run(main()) +``` + +#### Example - Using interrupts + +```python theme={null} +import asyncio +from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage + + +async def interruptible_task(): + options = ClaudeAgentOptions(allowed_tools=["Bash"], permission_mode="acceptEdits") + + async with ClaudeSDKClient(options=options) as client: + # Start a long-running task + await client.query("Count from 1 to 100 slowly, using the bash sleep command") + + # Let it run for a bit + await asyncio.sleep(2) + + # Interrupt the task + await client.interrupt() + print("Task interrupted!") + + # Drain the interrupted task's messages (including its ResultMessage) + async for message in client.receive_response(): + if isinstance(message, ResultMessage): + print(f"Interrupted task finished with subtype={message.subtype!r}") + # subtype is "error_during_execution" for interrupted tasks + + # Send a new command + await client.query("Just say hello instead") + + # Now receive the new response + async for message in client.receive_response(): + if isinstance(message, ResultMessage) and message.subtype == "success": + print(f"New result: {message.result}") + + +asyncio.run(interruptible_task()) +``` + + + **Buffer behavior after interrupt:** `interrupt()` sends a stop signal but does not clear the message buffer. Messages already produced by the interrupted task, including its `ResultMessage` (with `subtype="error_during_execution"`), remain in the stream. You must drain them with `receive_response()` before reading the response to a new query. If you send a new query immediately after `interrupt()` and call `receive_response()` only once, you'll receive the interrupted task's messages, not the new query's response. + + +#### Example - Advanced permission control + +```python theme={null} +from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions +from claude_agent_sdk.types import ( + PermissionResultAllow, + PermissionResultDeny, + ToolPermissionContext, +) + + +async def custom_permission_handler( + tool_name: str, input_data: dict, context: ToolPermissionContext +) -> PermissionResultAllow | PermissionResultDeny: + """Custom logic for tool permissions.""" + + # Block writes to system directories + if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"): + return PermissionResultDeny( + message="System directory write not allowed", interrupt=True + ) + + # Redirect sensitive file operations + if tool_name in ["Write", "Edit"] and "config" in input_data.get("file_path", ""): + safe_path = f"./sandbox/{input_data['file_path']}" + return PermissionResultAllow( + updated_input={**input_data, "file_path": safe_path} + ) + + # Allow everything else + return PermissionResultAllow(updated_input=input_data) + + +async def main(): + options = ClaudeAgentOptions( + can_use_tool=custom_permission_handler, allowed_tools=["Read", "Write", "Edit"] + ) + + async with ClaudeSDKClient(options=options) as client: + await client.query("Update the system config file") + + async for message in client.receive_response(): + # Will use sandbox path instead + print(message) + + +asyncio.run(main()) +``` + +## Types + + + **`@dataclass` vs `TypedDict`:** This SDK uses two kinds of types. Classes decorated with `@dataclass` (such as `ResultMessage`, `AgentDefinition`, `TextBlock`) are object instances at runtime and support attribute access: `msg.result`. Classes defined with `TypedDict` (such as `ThinkingConfigEnabled`, `McpStdioServerConfig`, `SyncHookJSONOutput`) are **plain dicts at runtime** and require key access: `config["budget_tokens"]`, not `config.budget_tokens`. The `ClassName(field=value)` call syntax works for both, but only dataclasses produce objects with attributes. + + +### `SdkMcpTool` + +Definition for an SDK MCP tool created with the `@tool` decorator. + +```python theme={null} +@dataclass +class SdkMcpTool(Generic[T]): + name: str + description: str + input_schema: type[T] | dict[str, Any] + handler: Callable[[T], Awaitable[dict[str, Any]]] + annotations: ToolAnnotations | None = None +``` + +| Property | Type | Description | +| :------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------- | +| `name` | `str` | Unique identifier for the tool | +| `description` | `str` | Human-readable description | +| `input_schema` | `type[T] \| dict[str, Any]` | Schema for input validation | +| `handler` | `Callable[[T], Awaitable[dict[str, Any]]]` | Async function that handles tool execution | +| `annotations` | `ToolAnnotations \| None` | Optional MCP tool annotations (e.g., `readOnlyHint`, `destructiveHint`, `openWorldHint`). From `mcp.types` | + +### `Transport` + +Abstract base class for custom transport implementations. Use this to communicate with the Claude process over a custom channel (for example, a remote connection instead of a local subprocess). + + + This is a low-level internal API. The interface may change in future releases. Custom implementations must be updated to match any interface changes. + + +```python theme={null} +from abc import ABC, abstractmethod +from collections.abc import AsyncIterator +from typing import Any + + +class Transport(ABC): + @abstractmethod + async def connect(self) -> None: ... + + @abstractmethod + async def write(self, data: str) -> None: ... + + @abstractmethod + def read_messages(self) -> AsyncIterator[dict[str, Any]]: ... + + @abstractmethod + async def close(self) -> None: ... + + @abstractmethod + def is_ready(self) -> bool: ... + + @abstractmethod + async def end_input(self) -> None: ... +``` + +| Method | Description | +| :---------------- | :-------------------------------------------------------------------------- | +| `connect()` | Connect the transport and prepare for communication | +| `write(data)` | Write raw data (JSON + newline) to the transport | +| `read_messages()` | Async iterator that yields parsed JSON messages | +| `close()` | Close the connection and clean up resources | +| `is_ready()` | Returns `True` if the transport can send and receive | +| `end_input()` | Close the input stream (for example, close stdin for subprocess transports) | + +Import: `from claude_agent_sdk import Transport` + +### `ClaudeAgentOptions` + +Configuration dataclass for Claude Code queries. + +```python theme={null} +@dataclass +class ClaudeAgentOptions: + tools: list[str] | ToolsPreset | None = None + allowed_tools: list[str] = field(default_factory=list) + system_prompt: str | SystemPromptPreset | None = None + mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict) + permission_mode: PermissionMode | None = None + continue_conversation: bool = False + resume: str | None = None + max_turns: int | None = None + max_budget_usd: float | None = None + disallowed_tools: list[str] = field(default_factory=list) + model: str | None = None + fallback_model: str | None = None + betas: list[SdkBeta] = field(default_factory=list) + output_format: dict[str, Any] | None = None + permission_prompt_tool_name: str | None = None + cwd: str | Path | None = None + cli_path: str | Path | None = None + settings: str | None = None + add_dirs: list[str | Path] = field(default_factory=list) + env: dict[str, str] = field(default_factory=dict) + extra_args: dict[str, str | None] = field(default_factory=dict) + max_buffer_size: int | None = None + debug_stderr: Any = sys.stderr # Deprecated + stderr: Callable[[str], None] | None = None + can_use_tool: CanUseTool | None = None + hooks: dict[HookEvent, list[HookMatcher]] | None = None + user: str | None = None + include_partial_messages: bool = False + fork_session: bool = False + agents: dict[str, AgentDefinition] | None = None + setting_sources: list[SettingSource] | None = None + sandbox: SandboxSettings | None = None + plugins: list[SdkPluginConfig] = field(default_factory=list) + max_thinking_tokens: int | None = None # Deprecated: use thinking instead + thinking: ThinkingConfig | None = None + effort: Literal["low", "medium", "high", "max"] | None = None + enable_file_checkpointing: bool = False +``` + +| Property | Type | Default | Description | +| :---------------------------- | :------------------------------------------------ | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Tools configuration. Use `{"type": "preset", "preset": "claude_code"}` for Claude Code's default tools | +| `allowed_tools` | `list[str]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools; unlisted tools fall through to `permission_mode` and `can_use_tool`. Use `disallowed_tools` to block tools. See [Permissions](/en/agent-sdk/permissions#allow-and-deny-rules) | +| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | System prompt configuration. Pass a string for custom prompt, or use `{"type": "preset", "preset": "claude_code"}` for Claude Code's system prompt. Add `"append"` to extend the preset | +| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP server configurations or path to config file | +| `permission_mode` | `PermissionMode \| None` | `None` | Permission mode for tool usage | +| `continue_conversation` | `bool` | `False` | Continue the most recent conversation | +| `resume` | `str \| None` | `None` | Session ID to resume | +| `max_turns` | `int \| None` | `None` | Maximum agentic turns (tool-use round trips) | +| `max_budget_usd` | `float \| None` | `None` | Maximum budget in USD for the session | +| `disallowed_tools` | `list[str]` | `[]` | Tools to always deny. Deny rules are checked first and override `allowed_tools` and `permission_mode` (including `bypassPermissions`) | +| `enable_file_checkpointing` | `bool` | `False` | Enable file change tracking for rewinding. See [File checkpointing](/en/agent-sdk/file-checkpointing) | +| `model` | `str \| None` | `None` | Claude model to use | +| `fallback_model` | `str \| None` | `None` | Fallback model to use if the primary model fails | +| `betas` | `list[SdkBeta]` | `[]` | Beta features to enable. See [`SdkBeta`](#sdk-beta) for available options | +| `output_format` | `dict[str, Any] \| None` | `None` | Output format for structured responses (e.g., `{"type": "json_schema", "schema": {...}}`). See [Structured outputs](/en/agent-sdk/structured-outputs) for details | +| `permission_prompt_tool_name` | `str \| None` | `None` | MCP tool name for permission prompts | +| `cwd` | `str \| Path \| None` | `None` | Current working directory | +| `cli_path` | `str \| Path \| None` | `None` | Custom path to the Claude Code CLI executable | +| `settings` | `str \| None` | `None` | Path to settings file | +| `add_dirs` | `list[str \| Path]` | `[]` | Additional directories Claude can access | +| `env` | `dict[str, str]` | `{}` | Environment variables | +| `extra_args` | `dict[str, str \| None]` | `{}` | Additional CLI arguments to pass directly to the CLI | +| `max_buffer_size` | `int \| None` | `None` | Maximum bytes when buffering CLI stdout | +| `debug_stderr` | `Any` | `sys.stderr` | *Deprecated* - File-like object for debug output. Use `stderr` callback instead | +| `stderr` | `Callable[[str], None] \| None` | `None` | Callback function for stderr output from CLI | +| `can_use_tool` | [`CanUseTool`](#can-use-tool) ` \| None` | `None` | Tool permission callback function. See [Permission types](#can-use-tool) for details | +| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Hook configurations for intercepting events | +| `user` | `str \| None` | `None` | User identifier | +| `include_partial_messages` | `bool` | `False` | Include partial message streaming events. When enabled, [`StreamEvent`](#stream-event) messages are yielded | +| `fork_session` | `bool` | `False` | When resuming with `resume`, fork to a new session ID instead of continuing the original session | +| `agents` | `dict[str, AgentDefinition] \| None` | `None` | Programmatically defined subagents | +| `plugins` | `list[SdkPluginConfig]` | `[]` | Load custom plugins from local paths. See [Plugins](/en/agent-sdk/plugins) for details | +| `sandbox` | [`SandboxSettings`](#sandbox-settings) ` \| None` | `None` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandbox-settings) for details | +| `setting_sources` | `list[SettingSource] \| None` | `None` (no settings) | Control which filesystem settings to load. When omitted, no settings are loaded. **Note:** Must include `"project"` to load CLAUDE.md files | +| `max_thinking_tokens` | `int \| None` | `None` | *Deprecated* - Maximum tokens for thinking blocks. Use `thinking` instead | +| `thinking` | [`ThinkingConfig`](#thinking-config) ` \| None` | `None` | Controls extended thinking behavior. Takes precedence over `max_thinking_tokens` | +| `effort` | `Literal["low", "medium", "high", "max"] \| None` | `None` | Effort level for thinking depth | + +### `OutputFormat` + +Configuration for structured output validation. Pass this as a `dict` to the `output_format` field on `ClaudeAgentOptions`: + +```python theme={null} +# Expected dict shape for output_format +{ + "type": "json_schema", + "schema": {...}, # Your JSON Schema definition +} +``` + +| Field | Required | Description | +| :------- | :------- | :------------------------------------------------- | +| `type` | Yes | Must be `"json_schema"` for JSON Schema validation | +| `schema` | Yes | JSON Schema definition for output validation | + +### `SystemPromptPreset` + +Configuration for using Claude Code's preset system prompt with optional additions. + +```python theme={null} +class SystemPromptPreset(TypedDict): + type: Literal["preset"] + preset: Literal["claude_code"] + append: NotRequired[str] +``` + +| Field | Required | Description | +| :------- | :------- | :------------------------------------------------------------ | +| `type` | Yes | Must be `"preset"` to use a preset system prompt | +| `preset` | Yes | Must be `"claude_code"` to use Claude Code's system prompt | +| `append` | No | Additional instructions to append to the preset system prompt | + +### `SettingSource` + +Controls which filesystem-based configuration sources the SDK loads settings from. + +```python theme={null} +SettingSource = Literal["user", "project", "local"] +``` + +| Value | Description | Location | +| :---------- | :------------------------------------------- | :---------------------------- | +| `"user"` | Global user settings | `~/.claude/settings.json` | +| `"project"` | Shared project settings (version controlled) | `.claude/settings.json` | +| `"local"` | Local project settings (gitignored) | `.claude/settings.local.json` | + +#### Default behavior + +When `setting_sources` is **omitted** or **`None`**, the SDK does **not** load any filesystem settings. This provides isolation for SDK applications. + +#### Why use setting\_sources + +**Load all filesystem settings (legacy behavior):** + +```python theme={null} +# Load all settings like SDK v0.0.x did +from claude_agent_sdk import query, ClaudeAgentOptions + +async for message in query( + prompt="Analyze this code", + options=ClaudeAgentOptions( + setting_sources=["user", "project", "local"] # Load all settings + ), +): + print(message) +``` + +**Load only specific setting sources:** + +```python theme={null} +# Load only project settings, ignore user and local +async for message in query( + prompt="Run CI checks", + options=ClaudeAgentOptions( + setting_sources=["project"] # Only .claude/settings.json + ), +): + print(message) +``` + +**Testing and CI environments:** + +```python theme={null} +# Ensure consistent behavior in CI by excluding local settings +async for message in query( + prompt="Run tests", + options=ClaudeAgentOptions( + setting_sources=["project"], # Only team-shared settings + permission_mode="bypassPermissions", + ), +): + print(message) +``` + +**SDK-only applications:** + +```python theme={null} +# Define everything programmatically (default behavior) +# No filesystem dependencies - setting_sources defaults to None +async for message in query( + prompt="Review this PR", + options=ClaudeAgentOptions( + # setting_sources=None is the default, no need to specify + agents={...}, + mcp_servers={...}, + allowed_tools=["Read", "Grep", "Glob"], + ), +): + print(message) +``` + +**Loading CLAUDE.md project instructions:** + +```python theme={null} +# Load project settings to include CLAUDE.md files +async for message in query( + prompt="Add a new feature following project conventions", + options=ClaudeAgentOptions( + system_prompt={ + "type": "preset", + "preset": "claude_code", # Use Claude Code's system prompt + }, + setting_sources=["project"], # Required to load CLAUDE.md from project + allowed_tools=["Read", "Write", "Edit"], + ), +): + print(message) +``` + +#### Settings precedence + +When multiple sources are loaded, settings are merged with this precedence (highest to lowest): + +1. Local settings (`.claude/settings.local.json`) +2. Project settings (`.claude/settings.json`) +3. User settings (`~/.claude/settings.json`) + +Programmatic options (like `agents`, `allowed_tools`) always override filesystem settings. + +### `AgentDefinition` + +Configuration for a subagent defined programmatically. + +```python theme={null} +@dataclass +class AgentDefinition: + description: str + prompt: str + tools: list[str] | None = None + model: Literal["sonnet", "opus", "haiku", "inherit"] | None = None + skills: list[str] | None = None + memory: Literal["user", "project", "local"] | None = None + mcpServers: list[str | dict[str, Any]] | None = None +``` + +| Field | Required | Description | +| :------------ | :------- | :-------------------------------------------------------------------------------------------------- | +| `description` | Yes | Natural language description of when to use this agent | +| `prompt` | Yes | The agent's system prompt | +| `tools` | No | Array of allowed tool names. If omitted, inherits all tools | +| `model` | No | Model override for this agent. If omitted, uses the main model | +| `skills` | No | List of skill names available to this agent | +| `memory` | No | Memory source for this agent: `"user"`, `"project"`, or `"local"` | +| `mcpServers` | No | MCP servers available to this agent. Each entry is a server name or an inline `{name: config}` dict | + +### `PermissionMode` + +Permission modes for controlling tool execution. + +```python theme={null} +PermissionMode = Literal[ + "default", # Standard permission behavior + "acceptEdits", # Auto-accept file edits + "plan", # Planning mode - no execution + "dontAsk", # Deny anything not pre-approved instead of prompting + "bypassPermissions", # Bypass all permission checks (use with caution) +] +``` + +### `CanUseTool` + +Type alias for tool permission callback functions. + +```python theme={null} +CanUseTool = Callable[ + [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult] +] +``` + +The callback receives: + +* `tool_name`: Name of the tool being called +* `input_data`: The tool's input parameters +* `context`: A `ToolPermissionContext` with additional information + +Returns a `PermissionResult` (either `PermissionResultAllow` or `PermissionResultDeny`). + +### `ToolPermissionContext` + +Context information passed to tool permission callbacks. + +```python theme={null} +@dataclass +class ToolPermissionContext: + signal: Any | None = None # Future: abort signal support + suggestions: list[PermissionUpdate] = field(default_factory=list) +``` + +| Field | Type | Description | +| :------------ | :----------------------- | :----------------------------------------- | +| `signal` | `Any \| None` | Reserved for future abort signal support | +| `suggestions` | `list[PermissionUpdate]` | Permission update suggestions from the CLI | + +### `PermissionResult` + +Union type for permission callback results. + +```python theme={null} +PermissionResult = PermissionResultAllow | PermissionResultDeny +``` + +### `PermissionResultAllow` + +Result indicating the tool call should be allowed. + +```python theme={null} +@dataclass +class PermissionResultAllow: + behavior: Literal["allow"] = "allow" + updated_input: dict[str, Any] | None = None + updated_permissions: list[PermissionUpdate] | None = None +``` + +| Field | Type | Default | Description | +| :-------------------- | :------------------------------- | :-------- | :---------------------------------------- | +| `behavior` | `Literal["allow"]` | `"allow"` | Must be "allow" | +| `updated_input` | `dict[str, Any] \| None` | `None` | Modified input to use instead of original | +| `updated_permissions` | `list[PermissionUpdate] \| None` | `None` | Permission updates to apply | + +### `PermissionResultDeny` + +Result indicating the tool call should be denied. + +```python theme={null} +@dataclass +class PermissionResultDeny: + behavior: Literal["deny"] = "deny" + message: str = "" + interrupt: bool = False +``` + +| Field | Type | Default | Description | +| :---------- | :---------------- | :------- | :----------------------------------------- | +| `behavior` | `Literal["deny"]` | `"deny"` | Must be "deny" | +| `message` | `str` | `""` | Message explaining why the tool was denied | +| `interrupt` | `bool` | `False` | Whether to interrupt the current execution | + +### `PermissionUpdate` + +Configuration for updating permissions programmatically. + +```python theme={null} +@dataclass +class PermissionUpdate: + type: Literal[ + "addRules", + "replaceRules", + "removeRules", + "setMode", + "addDirectories", + "removeDirectories", + ] + rules: list[PermissionRuleValue] | None = None + behavior: Literal["allow", "deny", "ask"] | None = None + mode: PermissionMode | None = None + directories: list[str] | None = None + destination: ( + Literal["userSettings", "projectSettings", "localSettings", "session"] | None + ) = None +``` + +| Field | Type | Description | +| :------------ | :---------------------------------------- | :---------------------------------------------- | +| `type` | `Literal[...]` | The type of permission update operation | +| `rules` | `list[PermissionRuleValue] \| None` | Rules for add/replace/remove operations | +| `behavior` | `Literal["allow", "deny", "ask"] \| None` | Behavior for rule-based operations | +| `mode` | `PermissionMode \| None` | Mode for setMode operation | +| `directories` | `list[str] \| None` | Directories for add/remove directory operations | +| `destination` | `Literal[...] \| None` | Where to apply the permission update | + +### `PermissionRuleValue` + +A rule to add, replace, or remove in a permission update. + +```python theme={null} +@dataclass +class PermissionRuleValue: + tool_name: str + rule_content: str | None = None +``` + +### `ToolsPreset` + +Preset tools configuration for using Claude Code's default tool set. + +```python theme={null} +class ToolsPreset(TypedDict): + type: Literal["preset"] + preset: Literal["claude_code"] +``` + +### `ThinkingConfig` + +Controls extended thinking behavior. A union of three configurations: + +```python theme={null} +class ThinkingConfigAdaptive(TypedDict): + type: Literal["adaptive"] + + +class ThinkingConfigEnabled(TypedDict): + type: Literal["enabled"] + budget_tokens: int + + +class ThinkingConfigDisabled(TypedDict): + type: Literal["disabled"] + + +ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled +``` + +| Variant | Fields | Description | +| :--------- | :---------------------- | :------------------------------------------- | +| `adaptive` | `type` | Claude adaptively decides when to think | +| `enabled` | `type`, `budget_tokens` | Enable thinking with a specific token budget | +| `disabled` | `type` | Disable thinking | + +Because these are `TypedDict` classes, they're plain dicts at runtime. Either construct them as dict literals or call the class like a constructor; both produce a `dict`. Access fields with `config["budget_tokens"]`, not `config.budget_tokens`: + +```python theme={null} +from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled + +# Option 1: dict literal (recommended, no import needed) +options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000}) + +# Option 2: constructor-style (returns a plain dict) +config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000) +print(config["budget_tokens"]) # 20000 +# config.budget_tokens would raise AttributeError +``` + +### `SdkBeta` + +Literal type for SDK beta features. + +```python theme={null} +SdkBeta = Literal["context-1m-2025-08-07"] +``` + +Use with the `betas` field in `ClaudeAgentOptions` to enable beta features. + + + The `context-1m-2025-08-07` beta is retired as of April 30, 2026. Passing this header with Claude Sonnet 4.5 or Sonnet 4 has no effect, and requests that exceed the standard 200k-token context window return an error. To use a 1M-token context window, migrate to [Claude Sonnet 4.6 or Claude Opus 4.6](https://platform.claude.com/docs/en/about-claude/models/overview), which include 1M context at standard pricing with no beta header required. + + +### `McpSdkServerConfig` + +Configuration for SDK MCP servers created with `create_sdk_mcp_server()`. + +```python theme={null} +class McpSdkServerConfig(TypedDict): + type: Literal["sdk"] + name: str + instance: Any # MCP Server instance +``` + +### `McpServerConfig` + +Union type for MCP server configurations. + +```python theme={null} +McpServerConfig = ( + McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig +) +``` + +#### `McpStdioServerConfig` + +```python theme={null} +class McpStdioServerConfig(TypedDict): + type: NotRequired[Literal["stdio"]] # Optional for backwards compatibility + command: str + args: NotRequired[list[str]] + env: NotRequired[dict[str, str]] +``` + +#### `McpSSEServerConfig` + +```python theme={null} +class McpSSEServerConfig(TypedDict): + type: Literal["sse"] + url: str + headers: NotRequired[dict[str, str]] +``` + +#### `McpHttpServerConfig` + +```python theme={null} +class McpHttpServerConfig(TypedDict): + type: Literal["http"] + url: str + headers: NotRequired[dict[str, str]] +``` + +### `McpServerStatusConfig` + +The configuration of an MCP server as reported by [`get_mcp_status()`](#methods). This is the union of all [`McpServerConfig`](#mcp-server-config) transport variants plus an output-only `claudeai-proxy` variant for servers proxied through claude.ai. + +```python theme={null} +McpServerStatusConfig = ( + McpStdioServerConfig + | McpSSEServerConfig + | McpHttpServerConfig + | McpSdkServerConfigStatus + | McpClaudeAIProxyServerConfig +) +``` + +`McpSdkServerConfigStatus` is the serializable form of [`McpSdkServerConfig`](#mcp-sdk-server-config) with only `type` (`"sdk"`) and `name` (`str`) fields; the in-process `instance` is omitted. `McpClaudeAIProxyServerConfig` has `type` (`"claudeai-proxy"`), `url` (`str`), and `id` (`str`) fields. + +### `McpStatusResponse` + +Response from [`ClaudeSDKClient.get_mcp_status()`](#methods). Wraps the list of server statuses under the `mcpServers` key. + +```python theme={null} +class McpStatusResponse(TypedDict): + mcpServers: list[McpServerStatus] +``` + +### `McpServerStatus` + +Status of a connected MCP server, contained in [`McpStatusResponse`](#mcp-status-response). + +```python theme={null} +class McpServerStatus(TypedDict): + name: str + status: McpServerConnectionStatus # "connected" | "failed" | "needs-auth" | "pending" | "disabled" + serverInfo: NotRequired[McpServerInfo] + error: NotRequired[str] + config: NotRequired[McpServerStatusConfig] + scope: NotRequired[str] + tools: NotRequired[list[McpToolInfo]] +``` + +| Field | Type | Description | +| :----------- | :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `name` | `str` | Server name | +| `status` | `str` | One of `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, or `"disabled"` | +| `serverInfo` | `dict` (optional) | Server name and version (`{"name": str, "version": str}`) | +| `error` | `str` (optional) | Error message if the server failed to connect | +| `config` | [`McpServerStatusConfig`](#mcp-server-status-config) (optional) | Server configuration. Same shape as [`McpServerConfig`](#mcp-server-config) (stdio, SSE, HTTP, or SDK), plus a `claudeai-proxy` variant for servers connected through claude.ai | +| `scope` | `str` (optional) | Configuration scope | +| `tools` | `list` (optional) | Tools provided by this server, each with `name`, `description`, and `annotations` fields | + +### `SdkPluginConfig` + +Configuration for loading plugins in the SDK. + +```python theme={null} +class SdkPluginConfig(TypedDict): + type: Literal["local"] + path: str +``` + +| Field | Type | Description | +| :----- | :----------------- | :--------------------------------------------------------- | +| `type` | `Literal["local"]` | Must be `"local"` (only local plugins currently supported) | +| `path` | `str` | Absolute or relative path to the plugin directory | + +**Example:** + +```python theme={null} +plugins = [ + {"type": "local", "path": "./my-plugin"}, + {"type": "local", "path": "/absolute/path/to/plugin"}, +] +``` + +For complete information on creating and using plugins, see [Plugins](/en/agent-sdk/plugins). + +## Message Types + +### `Message` + +Union type of all possible messages. + +```python theme={null} +Message = ( + UserMessage + | AssistantMessage + | SystemMessage + | ResultMessage + | StreamEvent + | RateLimitEvent +) +``` + +### `UserMessage` + +User input message. + +```python theme={null} +@dataclass +class UserMessage: + content: str | list[ContentBlock] + uuid: str | None = None + parent_tool_use_id: str | None = None + tool_use_result: dict[str, Any] | None = None +``` + +| Field | Type | Description | +| :------------------- | :-------------------------- | :---------------------------------------------------- | +| `content` | `str \| list[ContentBlock]` | Message content as text or content blocks | +| `uuid` | `str \| None` | Unique message identifier | +| `parent_tool_use_id` | `str \| None` | Tool use ID if this message is a tool result response | +| `tool_use_result` | `dict[str, Any] \| None` | Tool result data if applicable | + +### `AssistantMessage` + +Assistant response message with content blocks. + +```python theme={null} +@dataclass +class AssistantMessage: + content: list[ContentBlock] + model: str + parent_tool_use_id: str | None = None + error: AssistantMessageError | None = None + usage: dict[str, Any] | None = None + message_id: str | None = None +``` + +| Field | Type | Description | +| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------ | +| `content` | `list[ContentBlock]` | List of content blocks in the response | +| `model` | `str` | Model that generated the response | +| `parent_tool_use_id` | `str \| None` | Tool use ID if this is a nested response | +| `error` | [`AssistantMessageError`](#assistant-message-error) ` \| None` | Error type if the response encountered an error | +| `usage` | `dict[str, Any] \| None` | Per-message token usage (same keys as [`ResultMessage.usage`](#result-message)) | +| `message_id` | `str \| None` | API message ID. Multiple messages from one turn share the same ID | + +### `AssistantMessageError` + +Possible error types for assistant messages. + +```python theme={null} +AssistantMessageError = Literal[ + "authentication_failed", + "billing_error", + "rate_limit", + "invalid_request", + "server_error", + "max_output_tokens", + "unknown", +] +``` + +### `SystemMessage` + +System message with metadata. + +```python theme={null} +@dataclass +class SystemMessage: + subtype: str + data: dict[str, Any] +``` + +### `ResultMessage` + +Final result message with cost and usage information. + +```python theme={null} +@dataclass +class ResultMessage: + subtype: str + duration_ms: int + duration_api_ms: int + is_error: bool + num_turns: int + session_id: str + total_cost_usd: float | None = None + usage: dict[str, Any] | None = None + result: str | None = None + stop_reason: str | None = None + structured_output: Any = None + model_usage: dict[str, Any] | None = None +``` + +The `usage` dict contains the following keys when present: + +| Key | Type | Description | +| ----------------------------- | ----- | ---------------------------------------- | +| `input_tokens` | `int` | Total input tokens consumed. | +| `output_tokens` | `int` | Total output tokens generated. | +| `cache_creation_input_tokens` | `int` | Tokens used to create new cache entries. | +| `cache_read_input_tokens` | `int` | Tokens read from existing cache entries. | + +The `model_usage` dict maps model names to per-model usage. The inner dict keys use camelCase because the value is passed through unmodified from the underlying CLI process, matching the TypeScript [`ModelUsage`](/en/agent-sdk/typescript#model-usage) type: + +| Key | Type | Description | +| -------------------------- | ------- | ------------------------------------------ | +| `inputTokens` | `int` | Input tokens for this model. | +| `outputTokens` | `int` | Output tokens for this model. | +| `cacheReadInputTokens` | `int` | Cache read tokens for this model. | +| `cacheCreationInputTokens` | `int` | Cache creation tokens for this model. | +| `webSearchRequests` | `int` | Web search requests made by this model. | +| `costUSD` | `float` | Cost in USD for this model. | +| `contextWindow` | `int` | Context window size for this model. | +| `maxOutputTokens` | `int` | Maximum output token limit for this model. | + +### `StreamEvent` + +Stream event for partial message updates during streaming. Only received when `include_partial_messages=True` in `ClaudeAgentOptions`. Import via `from claude_agent_sdk.types import StreamEvent`. + +```python theme={null} +@dataclass +class StreamEvent: + uuid: str + session_id: str + event: dict[str, Any] # The raw Claude API stream event + parent_tool_use_id: str | None = None +``` + +| Field | Type | Description | +| :------------------- | :--------------- | :-------------------------------------------------- | +| `uuid` | `str` | Unique identifier for this event | +| `session_id` | `str` | Session identifier | +| `event` | `dict[str, Any]` | The raw Claude API stream event data | +| `parent_tool_use_id` | `str \| None` | Parent tool use ID if this event is from a subagent | + +### `RateLimitEvent` + +Emitted when rate limit status changes (for example, from `"allowed"` to `"allowed_warning"`). Use this to warn users before they hit a hard limit, or to back off when status is `"rejected"`. + +```python theme={null} +@dataclass +class RateLimitEvent: + rate_limit_info: RateLimitInfo + uuid: str + session_id: str +``` + +| Field | Type | Description | +| :---------------- | :---------------------------------- | :----------------------- | +| `rate_limit_info` | [`RateLimitInfo`](#rate-limit-info) | Current rate limit state | +| `uuid` | `str` | Unique event identifier | +| `session_id` | `str` | Session identifier | + +### `RateLimitInfo` + +Rate limit state carried by [`RateLimitEvent`](#rate-limit-event). + +```python theme={null} +RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"] +RateLimitType = Literal[ + "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", "overage" +] + + +@dataclass +class RateLimitInfo: + status: RateLimitStatus + resets_at: int | None = None + rate_limit_type: RateLimitType | None = None + utilization: float | None = None + overage_status: RateLimitStatus | None = None + overage_resets_at: int | None = None + overage_disabled_reason: str | None = None + raw: dict[str, Any] = field(default_factory=dict) +``` + +| Field | Type | Description | +| :------------------------ | :------------------------ | :---------------------------------------------------------------------------------------------------- | +| `status` | `RateLimitStatus` | Current status. `"allowed_warning"` means approaching the limit; `"rejected"` means the limit was hit | +| `resets_at` | `int \| None` | Unix timestamp when the rate limit window resets | +| `rate_limit_type` | `RateLimitType \| None` | Which rate limit window applies | +| `utilization` | `float \| None` | Fraction of the rate limit consumed (0.0 to 1.0) | +| `overage_status` | `RateLimitStatus \| None` | Status of pay-as-you-go overage usage, if applicable | +| `overage_resets_at` | `int \| None` | Unix timestamp when the overage window resets | +| `overage_disabled_reason` | `str \| None` | Why overage is unavailable, if status is `"rejected"` | +| `raw` | `dict[str, Any]` | Full raw dict from the CLI, including fields not modeled above | + +### `TaskStartedMessage` + +Emitted when a background task starts. A background task is anything tracked outside the main turn: a backgrounded Bash command, a subagent spawned via the Agent tool, or a remote agent. The `task_type` field tells you which. This naming is unrelated to the `Task`-to-`Agent` tool rename. + +```python theme={null} +@dataclass +class TaskStartedMessage(SystemMessage): + task_id: str + description: str + uuid: str + session_id: str + tool_use_id: str | None = None + task_type: str | None = None +``` + +| Field | Type | Description | +| :------------ | :------------ | :------------------------------------------------------------------------------- | +| `task_id` | `str` | Unique identifier for the task | +| `description` | `str` | Description of the task | +| `uuid` | `str` | Unique message identifier | +| `session_id` | `str` | Session identifier | +| `tool_use_id` | `str \| None` | Associated tool use ID | +| `task_type` | `str \| None` | Which kind of background task: `"local_bash"`, `"local_agent"`, `"remote_agent"` | + +### `TaskUsage` + +Token and timing data for a background task. + +```python theme={null} +class TaskUsage(TypedDict): + total_tokens: int + tool_uses: int + duration_ms: int +``` + +### `TaskProgressMessage` + +Emitted periodically with progress updates for a running background task. + +```python theme={null} +@dataclass +class TaskProgressMessage(SystemMessage): + task_id: str + description: str + usage: TaskUsage + uuid: str + session_id: str + tool_use_id: str | None = None + last_tool_name: str | None = None +``` + +| Field | Type | Description | +| :--------------- | :------------ | :---------------------------------- | +| `task_id` | `str` | Unique identifier for the task | +| `description` | `str` | Current status description | +| `usage` | `TaskUsage` | Token usage for this task so far | +| `uuid` | `str` | Unique message identifier | +| `session_id` | `str` | Session identifier | +| `tool_use_id` | `str \| None` | Associated tool use ID | +| `last_tool_name` | `str \| None` | Name of the last tool the task used | + +### `TaskNotificationMessage` + +Emitted when a task completes, fails, or is stopped. + +```python theme={null} +@dataclass +class TaskNotificationMessage(SystemMessage): + task_id: str + status: TaskNotificationStatus # "completed" | "failed" | "stopped" + output_file: str + summary: str + uuid: str + session_id: str + tool_use_id: str | None = None + usage: TaskUsage | None = None +``` + +| Field | Type | Description | +| :------------ | :----------------------- | :----------------------------------------------- | +| `task_id` | `str` | Unique identifier for the task | +| `status` | `TaskNotificationStatus` | One of `"completed"`, `"failed"`, or `"stopped"` | +| `output_file` | `str` | Path to the task output file | +| `summary` | `str` | Summary of the task result | +| `uuid` | `str` | Unique message identifier | +| `session_id` | `str` | Session identifier | +| `tool_use_id` | `str \| None` | Associated tool use ID | +| `usage` | `TaskUsage \| None` | Final token usage for the task | + +## Content Block Types + +### `ContentBlock` + +Union type of all content blocks. + +```python theme={null} +ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock +``` + +### `TextBlock` + +Text content block. + +```python theme={null} +@dataclass +class TextBlock: + text: str +``` + +### `ThinkingBlock` + +Thinking content block (for models with thinking capability). + +```python theme={null} +@dataclass +class ThinkingBlock: + thinking: str + signature: str +``` + +### `ToolUseBlock` + +Tool use request block. + +```python theme={null} +@dataclass +class ToolUseBlock: + id: str + name: str + input: dict[str, Any] +``` + +### `ToolResultBlock` + +Tool execution result block. + +```python theme={null} +@dataclass +class ToolResultBlock: + tool_use_id: str + content: str | list[dict[str, Any]] | None = None + is_error: bool | None = None +``` + +## Error Types + +### `ClaudeSDKError` + +Base exception class for all SDK errors. + +```python theme={null} +class ClaudeSDKError(Exception): + """Base error for Claude SDK.""" +``` + +### `CLINotFoundError` + +Raised when Claude Code CLI is not installed or not found. + +```python theme={null} +class CLINotFoundError(CLIConnectionError): + def __init__( + self, message: str = "Claude Code not found", cli_path: str | None = None + ): + """ + Args: + message: Error message (default: "Claude Code not found") + cli_path: Optional path to the CLI that was not found + """ +``` + +### `CLIConnectionError` + +Raised when connection to Claude Code fails. + +```python theme={null} +class CLIConnectionError(ClaudeSDKError): + """Failed to connect to Claude Code.""" +``` + +### `ProcessError` + +Raised when the Claude Code process fails. + +```python theme={null} +class ProcessError(ClaudeSDKError): + def __init__( + self, message: str, exit_code: int | None = None, stderr: str | None = None + ): + self.exit_code = exit_code + self.stderr = stderr +``` + +### `CLIJSONDecodeError` + +Raised when JSON parsing fails. + +```python theme={null} +class CLIJSONDecodeError(ClaudeSDKError): + def __init__(self, line: str, original_error: Exception): + """ + Args: + line: The line that failed to parse + original_error: The original JSON decode exception + """ + self.line = line + self.original_error = original_error +``` + +## Hook Types + +For a comprehensive guide on using hooks with examples and common patterns, see the [Hooks guide](/en/agent-sdk/hooks). + +### `HookEvent` + +Supported hook event types. + +```python theme={null} +HookEvent = Literal[ + "PreToolUse", # Called before tool execution + "PostToolUse", # Called after tool execution + "PostToolUseFailure", # Called when a tool execution fails + "UserPromptSubmit", # Called when user submits a prompt + "Stop", # Called when stopping execution + "SubagentStop", # Called when a subagent stops + "PreCompact", # Called before message compaction + "Notification", # Called for notification events + "SubagentStart", # Called when a subagent starts + "PermissionRequest", # Called when a permission decision is needed +] +``` + + + The TypeScript SDK supports additional hook events not yet available in Python: `SessionStart`, `SessionEnd`, `Setup`, `TeammateIdle`, `TaskCompleted`, `ConfigChange`, `WorktreeCreate`, and `WorktreeRemove`. + + +### `HookCallback` + +Type definition for hook callback functions. + +```python theme={null} +HookCallback = Callable[[HookInput, str | None, HookContext], Awaitable[HookJSONOutput]] +``` + +Parameters: + +* `input`: Strongly-typed hook input with discriminated unions based on `hook_event_name` (see [`HookInput`](#hook-input)) +* `tool_use_id`: Optional tool use identifier (for tool-related hooks) +* `context`: Hook context with additional information + +Returns a [`HookJSONOutput`](#hook-json-output) that may contain: + +* `decision`: `"block"` to block the action +* `systemMessage`: System message to add to the transcript +* `hookSpecificOutput`: Hook-specific output data + +### `HookContext` + +Context information passed to hook callbacks. + +```python theme={null} +class HookContext(TypedDict): + signal: Any | None # Future: abort signal support +``` + +### `HookMatcher` + +Configuration for matching hooks to specific events or tools. + +```python theme={null} +@dataclass +class HookMatcher: + matcher: str | None = ( + None # Tool name or pattern to match (e.g., "Bash", "Write|Edit") + ) + hooks: list[HookCallback] = field( + default_factory=list + ) # List of callbacks to execute + timeout: float | None = ( + None # Timeout in seconds for all hooks in this matcher (default: 60) + ) +``` + +### `HookInput` + +Union type of all hook input types. The actual type depends on the `hook_event_name` field. + +```python theme={null} +HookInput = ( + PreToolUseHookInput + | PostToolUseHookInput + | PostToolUseFailureHookInput + | UserPromptSubmitHookInput + | StopHookInput + | SubagentStopHookInput + | PreCompactHookInput + | NotificationHookInput + | SubagentStartHookInput + | PermissionRequestHookInput +) +``` + +### `BaseHookInput` + +Base fields present in all hook input types. + +```python theme={null} +class BaseHookInput(TypedDict): + session_id: str + transcript_path: str + cwd: str + permission_mode: NotRequired[str] +``` + +| Field | Type | Description | +| :---------------- | :--------------- | :---------------------------------- | +| `session_id` | `str` | Current session identifier | +| `transcript_path` | `str` | Path to the session transcript file | +| `cwd` | `str` | Current working directory | +| `permission_mode` | `str` (optional) | Current permission mode | + +### `PreToolUseHookInput` + +Input data for `PreToolUse` hook events. + +```python theme={null} +class PreToolUseHookInput(BaseHookInput): + hook_event_name: Literal["PreToolUse"] + tool_name: str + tool_input: dict[str, Any] + tool_use_id: str + agent_id: NotRequired[str] + agent_type: NotRequired[str] +``` + +| Field | Type | Description | +| :---------------- | :---------------------- | :----------------------------------------------------------------- | +| `hook_event_name` | `Literal["PreToolUse"]` | Always "PreToolUse" | +| `tool_name` | `str` | Name of the tool about to be executed | +| `tool_input` | `dict[str, Any]` | Input parameters for the tool | +| `tool_use_id` | `str` | Unique identifier for this tool use | +| `agent_id` | `str` (optional) | Subagent identifier, present when the hook fires inside a subagent | +| `agent_type` | `str` (optional) | Subagent type, present when the hook fires inside a subagent | + +### `PostToolUseHookInput` + +Input data for `PostToolUse` hook events. + +```python theme={null} +class PostToolUseHookInput(BaseHookInput): + hook_event_name: Literal["PostToolUse"] + tool_name: str + tool_input: dict[str, Any] + tool_response: Any + tool_use_id: str + agent_id: NotRequired[str] + agent_type: NotRequired[str] +``` + +| Field | Type | Description | +| :---------------- | :----------------------- | :----------------------------------------------------------------- | +| `hook_event_name` | `Literal["PostToolUse"]` | Always "PostToolUse" | +| `tool_name` | `str` | Name of the tool that was executed | +| `tool_input` | `dict[str, Any]` | Input parameters that were used | +| `tool_response` | `Any` | Response from the tool execution | +| `tool_use_id` | `str` | Unique identifier for this tool use | +| `agent_id` | `str` (optional) | Subagent identifier, present when the hook fires inside a subagent | +| `agent_type` | `str` (optional) | Subagent type, present when the hook fires inside a subagent | + +### `PostToolUseFailureHookInput` + +Input data for `PostToolUseFailure` hook events. Called when a tool execution fails. + +```python theme={null} +class PostToolUseFailureHookInput(BaseHookInput): + hook_event_name: Literal["PostToolUseFailure"] + tool_name: str + tool_input: dict[str, Any] + tool_use_id: str + error: str + is_interrupt: NotRequired[bool] + agent_id: NotRequired[str] + agent_type: NotRequired[str] +``` + +| Field | Type | Description | +| :---------------- | :------------------------------ | :----------------------------------------------------------------- | +| `hook_event_name` | `Literal["PostToolUseFailure"]` | Always "PostToolUseFailure" | +| `tool_name` | `str` | Name of the tool that failed | +| `tool_input` | `dict[str, Any]` | Input parameters that were used | +| `tool_use_id` | `str` | Unique identifier for this tool use | +| `error` | `str` | Error message from the failed execution | +| `is_interrupt` | `bool` (optional) | Whether the failure was caused by an interrupt | +| `agent_id` | `str` (optional) | Subagent identifier, present when the hook fires inside a subagent | +| `agent_type` | `str` (optional) | Subagent type, present when the hook fires inside a subagent | + +### `UserPromptSubmitHookInput` + +Input data for `UserPromptSubmit` hook events. + +```python theme={null} +class UserPromptSubmitHookInput(BaseHookInput): + hook_event_name: Literal["UserPromptSubmit"] + prompt: str +``` + +| Field | Type | Description | +| :---------------- | :---------------------------- | :-------------------------- | +| `hook_event_name` | `Literal["UserPromptSubmit"]` | Always "UserPromptSubmit" | +| `prompt` | `str` | The user's submitted prompt | + +### `StopHookInput` + +Input data for `Stop` hook events. + +```python theme={null} +class StopHookInput(BaseHookInput): + hook_event_name: Literal["Stop"] + stop_hook_active: bool +``` + +| Field | Type | Description | +| :----------------- | :---------------- | :------------------------------ | +| `hook_event_name` | `Literal["Stop"]` | Always "Stop" | +| `stop_hook_active` | `bool` | Whether the stop hook is active | + +### `SubagentStopHookInput` + +Input data for `SubagentStop` hook events. + +```python theme={null} +class SubagentStopHookInput(BaseHookInput): + hook_event_name: Literal["SubagentStop"] + stop_hook_active: bool + agent_id: str + agent_transcript_path: str + agent_type: str +``` + +| Field | Type | Description | +| :---------------------- | :------------------------ | :------------------------------------- | +| `hook_event_name` | `Literal["SubagentStop"]` | Always "SubagentStop" | +| `stop_hook_active` | `bool` | Whether the stop hook is active | +| `agent_id` | `str` | Unique identifier for the subagent | +| `agent_transcript_path` | `str` | Path to the subagent's transcript file | +| `agent_type` | `str` | Type of the subagent | + +### `PreCompactHookInput` + +Input data for `PreCompact` hook events. + +```python theme={null} +class PreCompactHookInput(BaseHookInput): + hook_event_name: Literal["PreCompact"] + trigger: Literal["manual", "auto"] + custom_instructions: str | None +``` + +| Field | Type | Description | +| :-------------------- | :-------------------------- | :--------------------------------- | +| `hook_event_name` | `Literal["PreCompact"]` | Always "PreCompact" | +| `trigger` | `Literal["manual", "auto"]` | What triggered the compaction | +| `custom_instructions` | `str \| None` | Custom instructions for compaction | + +### `NotificationHookInput` + +Input data for `Notification` hook events. + +```python theme={null} +class NotificationHookInput(BaseHookInput): + hook_event_name: Literal["Notification"] + message: str + title: NotRequired[str] + notification_type: str +``` + +| Field | Type | Description | +| :------------------ | :------------------------ | :--------------------------- | +| `hook_event_name` | `Literal["Notification"]` | Always "Notification" | +| `message` | `str` | Notification message content | +| `title` | `str` (optional) | Notification title | +| `notification_type` | `str` | Type of notification | + +### `SubagentStartHookInput` + +Input data for `SubagentStart` hook events. + +```python theme={null} +class SubagentStartHookInput(BaseHookInput): + hook_event_name: Literal["SubagentStart"] + agent_id: str + agent_type: str +``` + +| Field | Type | Description | +| :---------------- | :------------------------- | :--------------------------------- | +| `hook_event_name` | `Literal["SubagentStart"]` | Always "SubagentStart" | +| `agent_id` | `str` | Unique identifier for the subagent | +| `agent_type` | `str` | Type of the subagent | + +### `PermissionRequestHookInput` + +Input data for `PermissionRequest` hook events. Allows hooks to handle permission decisions programmatically. + +```python theme={null} +class PermissionRequestHookInput(BaseHookInput): + hook_event_name: Literal["PermissionRequest"] + tool_name: str + tool_input: dict[str, Any] + permission_suggestions: NotRequired[list[Any]] +``` + +| Field | Type | Description | +| :----------------------- | :----------------------------- | :---------------------------------------- | +| `hook_event_name` | `Literal["PermissionRequest"]` | Always "PermissionRequest" | +| `tool_name` | `str` | Name of the tool requesting permission | +| `tool_input` | `dict[str, Any]` | Input parameters for the tool | +| `permission_suggestions` | `list[Any]` (optional) | Suggested permission updates from the CLI | + +### `HookJSONOutput` + +Union type for hook callback return values. + +```python theme={null} +HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput +``` + +#### `SyncHookJSONOutput` + +Synchronous hook output with control and decision fields. + +```python theme={null} +class SyncHookJSONOutput(TypedDict): + # Control fields + continue_: NotRequired[bool] # Whether to proceed (default: True) + suppressOutput: NotRequired[bool] # Hide stdout from transcript + stopReason: NotRequired[str] # Message when continue is False + + # Decision fields + decision: NotRequired[Literal["block"]] + systemMessage: NotRequired[str] # Warning message for user + reason: NotRequired[str] # Feedback for Claude + + # Hook-specific output + hookSpecificOutput: NotRequired[HookSpecificOutput] +``` + + + Use `continue_` (with underscore) in Python code. It is automatically converted to `continue` when sent to the CLI. + + +#### `HookSpecificOutput` + +A `TypedDict` containing the hook event name and event-specific fields. The shape depends on the `hookEventName` value. For full details on available fields per hook event, see [Control execution with hooks](/en/agent-sdk/hooks#outputs). + +A discriminated union of event-specific output types. The `hookEventName` field determines which fields are valid. + +```python theme={null} +class PreToolUseHookSpecificOutput(TypedDict): + hookEventName: Literal["PreToolUse"] + permissionDecision: NotRequired[Literal["allow", "deny", "ask"]] + permissionDecisionReason: NotRequired[str] + updatedInput: NotRequired[dict[str, Any]] + additionalContext: NotRequired[str] + + +class PostToolUseHookSpecificOutput(TypedDict): + hookEventName: Literal["PostToolUse"] + additionalContext: NotRequired[str] + updatedMCPToolOutput: NotRequired[Any] + + +class PostToolUseFailureHookSpecificOutput(TypedDict): + hookEventName: Literal["PostToolUseFailure"] + additionalContext: NotRequired[str] + + +class UserPromptSubmitHookSpecificOutput(TypedDict): + hookEventName: Literal["UserPromptSubmit"] + additionalContext: NotRequired[str] + + +class NotificationHookSpecificOutput(TypedDict): + hookEventName: Literal["Notification"] + additionalContext: NotRequired[str] + + +class SubagentStartHookSpecificOutput(TypedDict): + hookEventName: Literal["SubagentStart"] + additionalContext: NotRequired[str] + + +class PermissionRequestHookSpecificOutput(TypedDict): + hookEventName: Literal["PermissionRequest"] + decision: dict[str, Any] + + +HookSpecificOutput = ( + PreToolUseHookSpecificOutput + | PostToolUseHookSpecificOutput + | PostToolUseFailureHookSpecificOutput + | UserPromptSubmitHookSpecificOutput + | NotificationHookSpecificOutput + | SubagentStartHookSpecificOutput + | PermissionRequestHookSpecificOutput +) +``` + +#### `AsyncHookJSONOutput` + +Async hook output that defers hook execution. + +```python theme={null} +class AsyncHookJSONOutput(TypedDict): + async_: Literal[True] # Set to True to defer execution + asyncTimeout: NotRequired[int] # Timeout in milliseconds +``` + + + Use `async_` (with underscore) in Python code. It is automatically converted to `async` when sent to the CLI. + + +### Hook Usage Example + +This example registers two hooks: one that blocks dangerous bash commands like `rm -rf /`, and another that logs all tool usage for auditing. The security hook only runs on Bash commands (via the `matcher`), while the logging hook runs on all tools. + +```python theme={null} +from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, HookContext +from typing import Any + + +async def validate_bash_command( + input_data: dict[str, Any], tool_use_id: str | None, context: HookContext +) -> dict[str, Any]: + """Validate and potentially block dangerous bash commands.""" + if input_data["tool_name"] == "Bash": + command = input_data["tool_input"].get("command", "") + if "rm -rf /" in command: + return { + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "deny", + "permissionDecisionReason": "Dangerous command blocked", + } + } + return {} + + +async def log_tool_use( + input_data: dict[str, Any], tool_use_id: str | None, context: HookContext +) -> dict[str, Any]: + """Log all tool usage for auditing.""" + print(f"Tool used: {input_data.get('tool_name')}") + return {} + + +options = ClaudeAgentOptions( + hooks={ + "PreToolUse": [ + HookMatcher( + matcher="Bash", hooks=[validate_bash_command], timeout=120 + ), # 2 min for validation + HookMatcher( + hooks=[log_tool_use] + ), # Applies to all tools (default 60s timeout) + ], + "PostToolUse": [HookMatcher(hooks=[log_tool_use])], + } +) + +async for message in query(prompt="Analyze this codebase", options=options): + print(message) +``` + +## Tool Input/Output Types + +Documentation of input/output schemas for all built-in Claude Code tools. While the Python SDK doesn't export these as types, they represent the structure of tool inputs and outputs in messages. + +### Agent + +**Tool name:** `Agent` (previously `Task`, which is still accepted as an alias) + +**Input:** + +```python theme={null} +{ + "description": str, # A short (3-5 word) description of the task + "prompt": str, # The task for the agent to perform + "subagent_type": str, # The type of specialized agent to use +} +``` + +**Output:** + +```python theme={null} +{ + "result": str, # Final result from the subagent + "usage": dict | None, # Token usage statistics + "total_cost_usd": float | None, # Total cost in USD + "duration_ms": int | None, # Execution duration in milliseconds +} +``` + +### AskUserQuestion + +**Tool name:** `AskUserQuestion` + +Asks the user clarifying questions during execution. See [Handle approvals and user input](/en/agent-sdk/user-input#handle-clarifying-questions) for usage details. + +**Input:** + +```python theme={null} +{ + "questions": [ # Questions to ask the user (1-4 questions) + { + "question": str, # The complete question to ask the user + "header": str, # Very short label displayed as a chip/tag (max 12 chars) + "options": [ # The available choices (2-4 options) + { + "label": str, # Display text for this option (1-5 words) + "description": str, # Explanation of what this option means + } + ], + "multiSelect": bool, # Set to true to allow multiple selections + } + ], + "answers": dict | None, # User answers populated by the permission system +} +``` + +**Output:** + +```python theme={null} +{ + "questions": [ # The questions that were asked + { + "question": str, + "header": str, + "options": [{"label": str, "description": str}], + "multiSelect": bool, + } + ], + "answers": dict[str, str], # Maps question text to answer string + # Multi-select answers are comma-separated +} +``` + +### Bash + +**Tool name:** `Bash` + +**Input:** + +```python theme={null} +{ + "command": str, # The command to execute + "timeout": int | None, # Optional timeout in milliseconds (max 600000) + "description": str | None, # Clear, concise description (5-10 words) + "run_in_background": bool | None, # Set to true to run in background +} +``` + +**Output:** + +```python theme={null} +{ + "output": str, # Combined stdout and stderr output + "exitCode": int, # Exit code of the command + "killed": bool | None, # Whether command was killed due to timeout + "shellId": str | None, # Shell ID for background processes +} +``` + +### Edit + +**Tool name:** `Edit` + +**Input:** + +```python theme={null} +{ + "file_path": str, # The absolute path to the file to modify + "old_string": str, # The text to replace + "new_string": str, # The text to replace it with + "replace_all": bool | None, # Replace all occurrences (default False) +} +``` + +**Output:** + +```python theme={null} +{ + "message": str, # Confirmation message + "replacements": int, # Number of replacements made + "file_path": str, # File path that was edited +} +``` + +### Read + +**Tool name:** `Read` + +**Input:** + +```python theme={null} +{ + "file_path": str, # The absolute path to the file to read + "offset": int | None, # The line number to start reading from + "limit": int | None, # The number of lines to read +} +``` + +**Output (Text files):** + +```python theme={null} +{ + "content": str, # File contents with line numbers + "total_lines": int, # Total number of lines in file + "lines_returned": int, # Lines actually returned +} +``` + +**Output (Images):** + +```python theme={null} +{ + "image": str, # Base64 encoded image data + "mime_type": str, # Image MIME type + "file_size": int, # File size in bytes +} +``` + +### Write + +**Tool name:** `Write` + +**Input:** + +```python theme={null} +{ + "file_path": str, # The absolute path to the file to write + "content": str, # The content to write to the file +} +``` + +**Output:** + +```python theme={null} +{ + "message": str, # Success message + "bytes_written": int, # Number of bytes written + "file_path": str, # File path that was written +} +``` + +### Glob + +**Tool name:** `Glob` + +**Input:** + +```python theme={null} +{ + "pattern": str, # The glob pattern to match files against + "path": str | None, # The directory to search in (defaults to cwd) +} +``` + +**Output:** + +```python theme={null} +{ + "matches": list[str], # Array of matching file paths + "count": int, # Number of matches found + "search_path": str, # Search directory used +} +``` + +### Grep + +**Tool name:** `Grep` + +**Input:** + +```python theme={null} +{ + "pattern": str, # The regular expression pattern + "path": str | None, # File or directory to search in + "glob": str | None, # Glob pattern to filter files + "type": str | None, # File type to search + "output_mode": str | None, # "content", "files_with_matches", or "count" + "-i": bool | None, # Case insensitive search + "-n": bool | None, # Show line numbers + "-B": int | None, # Lines to show before each match + "-A": int | None, # Lines to show after each match + "-C": int | None, # Lines to show before and after + "head_limit": int | None, # Limit output to first N lines/entries + "multiline": bool | None, # Enable multiline mode +} +``` + +**Output (content mode):** + +```python theme={null} +{ + "matches": [ + { + "file": str, + "line_number": int | None, + "line": str, + "before_context": list[str] | None, + "after_context": list[str] | None, + } + ], + "total_matches": int, +} +``` + +**Output (files\_with\_matches mode):** + +```python theme={null} +{ + "files": list[str], # Files containing matches + "count": int, # Number of files with matches +} +``` + +### NotebookEdit + +**Tool name:** `NotebookEdit` + +**Input:** + +```python theme={null} +{ + "notebook_path": str, # Absolute path to the Jupyter notebook + "cell_id": str | None, # The ID of the cell to edit + "new_source": str, # The new source for the cell + "cell_type": "code" | "markdown" | None, # The type of the cell + "edit_mode": "replace" | "insert" | "delete" | None, # Edit operation type +} +``` + +**Output:** + +```python theme={null} +{ + "message": str, # Success message + "edit_type": "replaced" | "inserted" | "deleted", # Type of edit performed + "cell_id": str | None, # Cell ID that was affected + "total_cells": int, # Total cells in notebook after edit +} +``` + +### WebFetch + +**Tool name:** `WebFetch` + +**Input:** + +```python theme={null} +{ + "url": str, # The URL to fetch content from + "prompt": str, # The prompt to run on the fetched content +} +``` + +**Output:** + +```python theme={null} +{ + "response": str, # AI model's response to the prompt + "url": str, # URL that was fetched + "final_url": str | None, # Final URL after redirects + "status_code": int | None, # HTTP status code +} +``` + +### WebSearch + +**Tool name:** `WebSearch` + +**Input:** + +```python theme={null} +{ + "query": str, # The search query to use + "allowed_domains": list[str] | None, # Only include results from these domains + "blocked_domains": list[str] | None, # Never include results from these domains +} +``` + +**Output:** + +```python theme={null} +{ + "results": [{"title": str, "url": str, "snippet": str, "metadata": dict | None}], + "total_results": int, + "query": str, +} +``` + +### TodoWrite + +**Tool name:** `TodoWrite` + +**Input:** + +```python theme={null} +{ + "todos": [ + { + "content": str, # The task description + "status": "pending" | "in_progress" | "completed", # Task status + "activeForm": str, # Active form of the description + } + ] +} +``` + +**Output:** + +```python theme={null} +{ + "message": str, # Success message + "stats": {"total": int, "pending": int, "in_progress": int, "completed": int}, +} +``` + +### BashOutput + +**Tool name:** `BashOutput` + +**Input:** + +```python theme={null} +{ + "bash_id": str, # The ID of the background shell + "filter": str | None, # Optional regex to filter output lines +} +``` + +**Output:** + +```python theme={null} +{ + "output": str, # New output since last check + "status": "running" | "completed" | "failed", # Current shell status + "exitCode": int | None, # Exit code when completed +} +``` + +### KillBash + +**Tool name:** `KillBash` + +**Input:** + +```python theme={null} +{ + "shell_id": str # The ID of the background shell to kill +} +``` + +**Output:** + +```python theme={null} +{ + "message": str, # Success message + "shell_id": str, # ID of the killed shell +} +``` + +### ExitPlanMode + +**Tool name:** `ExitPlanMode` + +**Input:** + +```python theme={null} +{ + "plan": str # The plan to run by the user for approval +} +``` + +**Output:** + +```python theme={null} +{ + "message": str, # Confirmation message + "approved": bool | None, # Whether user approved the plan +} +``` + +### ListMcpResources + +**Tool name:** `ListMcpResources` + +**Input:** + +```python theme={null} +{ + "server": str | None # Optional server name to filter resources by +} +``` + +**Output:** + +```python theme={null} +{ + "resources": [ + { + "uri": str, + "name": str, + "description": str | None, + "mimeType": str | None, + "server": str, + } + ], + "total": int, +} +``` + +### ReadMcpResource + +**Tool name:** `ReadMcpResource` + +**Input:** + +```python theme={null} +{ + "server": str, # The MCP server name + "uri": str, # The resource URI to read +} +``` + +**Output:** + +```python theme={null} +{ + "contents": [ + {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None} + ], + "server": str, +} +``` + +## Advanced Features with ClaudeSDKClient + +### Building a Continuous Conversation Interface + +```python theme={null} +from claude_agent_sdk import ( + ClaudeSDKClient, + ClaudeAgentOptions, + AssistantMessage, + TextBlock, +) +import asyncio + + +class ConversationSession: + """Maintains a single conversation session with Claude.""" + + def __init__(self, options: ClaudeAgentOptions | None = None): + self.client = ClaudeSDKClient(options) + self.turn_count = 0 + + async def start(self): + await self.client.connect() + print("Starting conversation session. Claude will remember context.") + print( + "Commands: 'exit' to quit, 'interrupt' to stop current task, 'new' for new session" + ) + + while True: + user_input = input(f"\n[Turn {self.turn_count + 1}] You: ") + + if user_input.lower() == "exit": + break + elif user_input.lower() == "interrupt": + await self.client.interrupt() + print("Task interrupted!") + continue + elif user_input.lower() == "new": + # Disconnect and reconnect for a fresh session + await self.client.disconnect() + await self.client.connect() + self.turn_count = 0 + print("Started new conversation session (previous context cleared)") + continue + + # Send message - the session retains all previous messages + await self.client.query(user_input) + self.turn_count += 1 + + # Process response + print(f"[Turn {self.turn_count}] Claude: ", end="") + async for message in self.client.receive_response(): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(block.text, end="") + print() # New line after response + + await self.client.disconnect() + print(f"Conversation ended after {self.turn_count} turns.") + + +async def main(): + options = ClaudeAgentOptions( + allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits" + ) + session = ConversationSession(options) + await session.start() + + +# Example conversation: +# Turn 1 - You: "Create a file called hello.py" +# Turn 1 - Claude: "I'll create a hello.py file for you..." +# Turn 2 - You: "What's in that file?" +# Turn 2 - Claude: "The hello.py file I just created contains..." (remembers!) +# Turn 3 - You: "Add a main function to it" +# Turn 3 - Claude: "I'll add a main function to hello.py..." (knows which file!) + +asyncio.run(main()) +``` + +### Using Hooks for Behavior Modification + +```python theme={null} +from claude_agent_sdk import ( + ClaudeSDKClient, + ClaudeAgentOptions, + HookMatcher, + HookContext, +) +import asyncio +from typing import Any + + +async def pre_tool_logger( + input_data: dict[str, Any], tool_use_id: str | None, context: HookContext +) -> dict[str, Any]: + """Log all tool usage before execution.""" + tool_name = input_data.get("tool_name", "unknown") + print(f"[PRE-TOOL] About to use: {tool_name}") + + # You can modify or block the tool execution here + if tool_name == "Bash" and "rm -rf" in str(input_data.get("tool_input", {})): + return { + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "deny", + "permissionDecisionReason": "Dangerous command blocked", + } + } + return {} + + +async def post_tool_logger( + input_data: dict[str, Any], tool_use_id: str | None, context: HookContext +) -> dict[str, Any]: + """Log results after tool execution.""" + tool_name = input_data.get("tool_name", "unknown") + print(f"[POST-TOOL] Completed: {tool_name}") + return {} + + +async def user_prompt_modifier( + input_data: dict[str, Any], tool_use_id: str | None, context: HookContext +) -> dict[str, Any]: + """Add context to user prompts.""" + original_prompt = input_data.get("prompt", "") + + # Add a timestamp as additional context for Claude to see + from datetime import datetime + + timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S") + + return { + "hookSpecificOutput": { + "hookEventName": "UserPromptSubmit", + "additionalContext": f"[Submitted at {timestamp}] Original prompt: {original_prompt}", + } + } + + +async def main(): + options = ClaudeAgentOptions( + hooks={ + "PreToolUse": [ + HookMatcher(hooks=[pre_tool_logger]), + HookMatcher(matcher="Bash", hooks=[pre_tool_logger]), + ], + "PostToolUse": [HookMatcher(hooks=[post_tool_logger])], + "UserPromptSubmit": [HookMatcher(hooks=[user_prompt_modifier])], + }, + allowed_tools=["Read", "Write", "Bash"], + ) + + async with ClaudeSDKClient(options=options) as client: + await client.query("List files in current directory") + + async for message in client.receive_response(): + # Hooks will automatically log tool usage + pass + + +asyncio.run(main()) +``` + +### Real-time Progress Monitoring + +```python theme={null} +from claude_agent_sdk import ( + ClaudeSDKClient, + ClaudeAgentOptions, + AssistantMessage, + ToolUseBlock, + ToolResultBlock, + TextBlock, +) +import asyncio + + +async def monitor_progress(): + options = ClaudeAgentOptions( + allowed_tools=["Write", "Bash"], permission_mode="acceptEdits" + ) + + async with ClaudeSDKClient(options=options) as client: + await client.query("Create 5 Python files with different sorting algorithms") + + # Monitor progress in real-time + async for message in client.receive_response(): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, ToolUseBlock): + if block.name == "Write": + file_path = block.input.get("file_path", "") + print(f"Creating: {file_path}") + elif isinstance(block, ToolResultBlock): + print("Completed tool execution") + elif isinstance(block, TextBlock): + print(f"Claude says: {block.text[:100]}...") + + print("Task completed!") + + +asyncio.run(monitor_progress()) +``` + +## Example Usage + +### Basic file operations (using query) + +```python theme={null} +from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock +import asyncio + + +async def create_project(): + options = ClaudeAgentOptions( + allowed_tools=["Read", "Write", "Bash"], + permission_mode="acceptEdits", + cwd="/home/user/project", + ) + + async for message in query( + prompt="Create a Python project structure with setup.py", options=options + ): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, ToolUseBlock): + print(f"Using tool: {block.name}") + + +asyncio.run(create_project()) +``` + +### Error handling + +```python theme={null} +from claude_agent_sdk import query, CLINotFoundError, ProcessError, CLIJSONDecodeError + +try: + async for message in query(prompt="Hello"): + print(message) +except CLINotFoundError: + print( + "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk" + ) +except ProcessError as e: + print(f"Process failed with exit code: {e.exit_code}") +except CLIJSONDecodeError as e: + print(f"Failed to parse response: {e}") +``` + +### Streaming mode with client + +```python theme={null} +from claude_agent_sdk import ClaudeSDKClient +import asyncio + + +async def interactive_session(): + async with ClaudeSDKClient() as client: + # Send initial message + await client.query("What's the weather like?") + + # Process responses + async for msg in client.receive_response(): + print(msg) + + # Send follow-up + await client.query("Tell me more about that") + + # Process follow-up response + async for msg in client.receive_response(): + print(msg) + + +asyncio.run(interactive_session()) +``` + +### Using custom tools with ClaudeSDKClient + +```python theme={null} +from claude_agent_sdk import ( + ClaudeSDKClient, + ClaudeAgentOptions, + tool, + create_sdk_mcp_server, + AssistantMessage, + TextBlock, +) +import asyncio +from typing import Any + + +# Define custom tools with @tool decorator +@tool("calculate", "Perform mathematical calculations", {"expression": str}) +async def calculate(args: dict[str, Any]) -> dict[str, Any]: + try: + result = eval(args["expression"], {"__builtins__": {}}) + return {"content": [{"type": "text", "text": f"Result: {result}"}]} + except Exception as e: + return { + "content": [{"type": "text", "text": f"Error: {str(e)}"}], + "is_error": True, + } + + +@tool("get_time", "Get current time", {}) +async def get_time(args: dict[str, Any]) -> dict[str, Any]: + from datetime import datetime + + current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S") + return {"content": [{"type": "text", "text": f"Current time: {current_time}"}]} + + +async def main(): + # Create SDK MCP server with custom tools + my_server = create_sdk_mcp_server( + name="utilities", version="1.0.0", tools=[calculate, get_time] + ) + + # Configure options with the server + options = ClaudeAgentOptions( + mcp_servers={"utils": my_server}, + allowed_tools=["mcp__utils__calculate", "mcp__utils__get_time"], + ) + + # Use ClaudeSDKClient for interactive tool usage + async with ClaudeSDKClient(options=options) as client: + await client.query("What's 123 * 456?") + + # Process calculation response + async for message in client.receive_response(): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(f"Calculation: {block.text}") + + # Follow up with time query + await client.query("What time is it now?") + + async for message in client.receive_response(): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(f"Time: {block.text}") + + +asyncio.run(main()) +``` + +## Sandbox Configuration + +### `SandboxSettings` + +Configuration for sandbox behavior. Use this to enable command sandboxing and configure network restrictions programmatically. + +```python theme={null} +class SandboxSettings(TypedDict, total=False): + enabled: bool + autoAllowBashIfSandboxed: bool + excludedCommands: list[str] + allowUnsandboxedCommands: bool + network: SandboxNetworkConfig + ignoreViolations: SandboxIgnoreViolations + enableWeakerNestedSandbox: bool +``` + +| Property | Type | Default | Description | +| :-------------------------- | :------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `enabled` | `bool` | `False` | Enable sandbox mode for command execution | +| `autoAllowBashIfSandboxed` | `bool` | `True` | Auto-approve bash commands when sandbox is enabled | +| `excludedCommands` | `list[str]` | `[]` | Commands that always bypass sandbox restrictions (e.g., `["docker"]`). These run unsandboxed automatically without model involvement | +| `allowUnsandboxedCommands` | `bool` | `True` | Allow the model to request running commands outside the sandbox. When `True`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) | +| `network` | [`SandboxNetworkConfig`](#sandbox-network-config) | `None` | Network-specific sandbox configuration | +| `ignoreViolations` | [`SandboxIgnoreViolations`](#sandbox-ignore-violations) | `None` | Configure which sandbox violations to ignore | +| `enableWeakerNestedSandbox` | `bool` | `False` | Enable a weaker nested sandbox for compatibility | + + + **Filesystem and network access restrictions** are NOT configured via sandbox settings. Instead, they are derived from [permission rules](/en/settings#permission-settings): + + * **Filesystem read restrictions**: Read deny rules + * **Filesystem write restrictions**: Edit allow/deny rules + * **Network restrictions**: WebFetch allow/deny rules + + Use sandbox settings for command execution sandboxing, and permission rules for filesystem and network access control. + + +#### Example usage + +```python theme={null} +from claude_agent_sdk import query, ClaudeAgentOptions, SandboxSettings + +sandbox_settings: SandboxSettings = { + "enabled": True, + "autoAllowBashIfSandboxed": True, + "network": {"allowLocalBinding": True}, +} + +async for message in query( + prompt="Build and test my project", + options=ClaudeAgentOptions(sandbox=sandbox_settings), +): + print(message) +``` + + + **Unix socket security**: The `allowUnixSockets` option can grant access to powerful system services. For example, allowing `/var/run/docker.sock` effectively grants full host system access through the Docker API, bypassing sandbox isolation. Only allow Unix sockets that are strictly necessary and understand the security implications of each. + + +### `SandboxNetworkConfig` + +Network-specific configuration for sandbox mode. + +```python theme={null} +class SandboxNetworkConfig(TypedDict, total=False): + allowLocalBinding: bool + allowUnixSockets: list[str] + allowAllUnixSockets: bool + httpProxyPort: int + socksProxyPort: int +``` + +| Property | Type | Default | Description | +| :-------------------- | :---------- | :------ | :---------------------------------------------------------------- | +| `allowLocalBinding` | `bool` | `False` | Allow processes to bind to local ports (e.g., for dev servers) | +| `allowUnixSockets` | `list[str]` | `[]` | Unix socket paths that processes can access (e.g., Docker socket) | +| `allowAllUnixSockets` | `bool` | `False` | Allow access to all Unix sockets | +| `httpProxyPort` | `int` | `None` | HTTP proxy port for network requests | +| `socksProxyPort` | `int` | `None` | SOCKS proxy port for network requests | + +### `SandboxIgnoreViolations` + +Configuration for ignoring specific sandbox violations. + +```python theme={null} +class SandboxIgnoreViolations(TypedDict, total=False): + file: list[str] + network: list[str] +``` + +| Property | Type | Default | Description | +| :-------- | :---------- | :------ | :------------------------------------------ | +| `file` | `list[str]` | `[]` | File path patterns to ignore violations for | +| `network` | `list[str]` | `[]` | Network patterns to ignore violations for | + +### Permissions Fallback for Unsandboxed Commands + +When `allowUnsandboxedCommands` is enabled, the model can request to run commands outside the sandbox by setting `dangerouslyDisableSandbox: True` in the tool input. These requests fall back to the existing permissions system, meaning your `can_use_tool` handler will be invoked, allowing you to implement custom authorization logic. + + + **`excludedCommands` vs `allowUnsandboxedCommands`:** + + * `excludedCommands`: A static list of commands that always bypass the sandbox automatically (e.g., `["docker"]`). The model has no control over this. + * `allowUnsandboxedCommands`: Lets the model decide at runtime whether to request unsandboxed execution by setting `dangerouslyDisableSandbox: True` in the tool input. + + +```python theme={null} +from claude_agent_sdk import ( + query, + ClaudeAgentOptions, + HookMatcher, + PermissionResultAllow, + PermissionResultDeny, + ToolPermissionContext, +) + + +async def can_use_tool( + tool: str, input: dict, context: ToolPermissionContext +) -> PermissionResultAllow | PermissionResultDeny: + # Check if the model is requesting to bypass the sandbox + if tool == "Bash" and input.get("dangerouslyDisableSandbox"): + # The model is requesting to run this command outside the sandbox + print(f"Unsandboxed command requested: {input.get('command')}") + + if is_command_authorized(input.get("command")): + return PermissionResultAllow() + return PermissionResultDeny( + message="Command not authorized for unsandboxed execution" + ) + return PermissionResultAllow() + + +# Required: dummy hook keeps the stream open for can_use_tool +async def dummy_hook(input_data, tool_use_id, context): + return {"continue_": True} + + +async def prompt_stream(): + yield { + "type": "user", + "message": {"role": "user", "content": "Deploy my application"}, + } + + +async def main(): + async for message in query( + prompt=prompt_stream(), + options=ClaudeAgentOptions( + sandbox={ + "enabled": True, + "allowUnsandboxedCommands": True, # Model can request unsandboxed execution + }, + permission_mode="default", + can_use_tool=can_use_tool, + hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]}, + ), + ): + print(message) +``` + +This pattern enables you to: + +* **Audit model requests**: Log when the model requests unsandboxed execution +* **Implement allowlists**: Only permit specific commands to run unsandboxed +* **Add approval workflows**: Require explicit authorization for privileged operations + + + Commands running with `dangerouslyDisableSandbox: True` have full system access. Ensure your `can_use_tool` handler validates these requests carefully. + + If `permission_mode` is set to `bypassPermissions` and `allow_unsandboxed_commands` is enabled, the model can autonomously execute commands outside the sandbox without any approval prompts. This combination effectively allows the model to escape sandbox isolation silently. + + +## See also + +* [SDK overview](/en/agent-sdk/overview) - General SDK concepts +* [TypeScript SDK reference](/en/agent-sdk/typescript) - TypeScript SDK documentation +* [CLI reference](/en/cli-reference) - Command-line interface +* [Common workflows](/en/common-workflows) - Step-by-step guides diff --git a/content/en/docs/claude-code/agent-sdk/quickstart.md b/content/en/docs/claude-code/agent-sdk/quickstart.md new file mode 100644 index 000000000..768cdc9d1 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/quickstart.md @@ -0,0 +1,317 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Quickstart + +> Get started with the Python or TypeScript Agent SDK to build AI agents that work autonomously + +Use the Agent SDK to build an AI agent that reads your code, finds bugs, and fixes them, all without manual intervention. + +**What you'll do:** + +1. Set up a project with the Agent SDK +2. Create a file with some buggy code +3. Run an agent that finds and fixes the bugs automatically + +## Prerequisites + +* **Node.js 18+** or **Python 3.10+** +* An **Anthropic account** ([sign up here](https://platform.claude.com/)) + +## Setup + + + + Create a new directory for this quickstart: + + ```bash theme={null} + mkdir my-agent && cd my-agent + ``` + + For your own projects, you can run the SDK from any folder; it will have access to files in that directory and its subdirectories by default. + + + + Install the Agent SDK package for your language: + + + + ```bash theme={null} + npm install @anthropic-ai/claude-agent-sdk + ``` + + + + [uv Python package manager](https://docs.astral.sh/uv/) is a fast Python package manager that handles virtual environments automatically: + + ```bash theme={null} + uv init && uv add claude-agent-sdk + ``` + + + + Create a virtual environment first, then install: + + ```bash theme={null} + python3 -m venv .venv && source .venv/bin/activate + pip3 install claude-agent-sdk + ``` + + + + + + Get an API key from the [Claude Console](https://platform.claude.com/), then create a `.env` file in your project directory: + + ```bash theme={null} + ANTHROPIC_API_KEY=your-api-key + ``` + + The SDK also supports authentication via third-party API providers: + + * **Amazon Bedrock**: set `CLAUDE_CODE_USE_BEDROCK=1` environment variable and configure AWS credentials + * **Google Vertex AI**: set `CLAUDE_CODE_USE_VERTEX=1` environment variable and configure Google Cloud credentials + * **Microsoft Azure**: set `CLAUDE_CODE_USE_FOUNDRY=1` environment variable and configure Azure credentials + + See the setup guides for [Bedrock](/en/amazon-bedrock), [Vertex AI](/en/google-vertex-ai), or [Azure AI Foundry](/en/microsoft-foundry) for details. + + + Unless previously approved, Anthropic does not allow third party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK. Please use the API key authentication methods described in this document instead. + + + + +## Create a buggy file + +This quickstart walks you through building an agent that can find and fix bugs in code. First, you need a file with some intentional bugs for the agent to fix. Create `utils.py` in the `my-agent` directory and paste the following code: + +```python theme={null} +def calculate_average(numbers): + total = 0 + for num in numbers: + total += num + return total / len(numbers) + + +def get_user_name(user): + return user["name"].upper() +``` + +This code has two bugs: + +1. `calculate_average([])` crashes with division by zero +2. `get_user_name(None)` crashes with a TypeError + +## Build an agent that finds and fixes bugs + +Create `agent.py` if you're using the Python SDK, or `agent.ts` for TypeScript: + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage + + + async def main(): + # Agentic loop: streams messages as Claude works + async for message in query( + prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Glob"], # Tools Claude can use + permission_mode="acceptEdits", # Auto-approve file edits + ), + ): + # Print human-readable output + if isinstance(message, AssistantMessage): + for block in message.content: + if hasattr(block, "text"): + print(block.text) # Claude's reasoning + elif hasattr(block, "name"): + print(f"Tool: {block.name}") # Tool being called + elif isinstance(message, ResultMessage): + print(f"Done: {message.subtype}") # Final result + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Agentic loop: streams messages as Claude works + for await (const message of query({ + prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.", + options: { + allowedTools: ["Read", "Edit", "Glob"], // Tools Claude can use + permissionMode: "acceptEdits" // Auto-approve file edits + } + })) { + // Print human-readable output + if (message.type === "assistant" && message.message?.content) { + for (const block of message.message.content) { + if ("text" in block) { + console.log(block.text); // Claude's reasoning + } else if ("name" in block) { + console.log(`Tool: ${block.name}`); // Tool being called + } + } + } else if (message.type === "result") { + console.log(`Done: ${message.subtype}`); // Final result + } + } + ``` + + +This code has three main parts: + +1. **`query`**: the main entry point that creates the agentic loop. It returns an async iterator, so you use `async for` to stream messages as Claude works. See the full API in the [Python](/en/agent-sdk/python#query) or [TypeScript](/en/agent-sdk/typescript#query) SDK reference. + +2. **`prompt`**: what you want Claude to do. Claude figures out which tools to use based on the task. + +3. **`options`**: configuration for the agent. This example uses `allowedTools` to pre-approve `Read`, `Edit`, and `Glob`, and `permissionMode: "acceptEdits"` to auto-approve file changes. Other options include `systemPrompt`, `mcpServers`, and more. See all options for [Python](/en/agent-sdk/python#claude-agent-options) or [TypeScript](/en/agent-sdk/typescript#options). + +The `async for` loop keeps running as Claude thinks, calls tools, observes results, and decides what to do next. Each iteration yields a message: Claude's reasoning, a tool call, a tool result, or the final outcome. The SDK handles the orchestration (tool execution, context management, retries) so you just consume the stream. The loop ends when Claude finishes the task or hits an error. + +The message handling inside the loop filters for human-readable output. Without filtering, you'd see raw message objects including system initialization and internal state, which is useful for debugging but noisy otherwise. + + + This example uses streaming to show progress in real-time. If you don't need live output (e.g., for background jobs or CI pipelines), you can collect all messages at once. See [Streaming vs. single-turn mode](/en/agent-sdk/streaming-vs-single-mode) for details. + + +### Run your agent + +Your agent is ready. Run it with the following command: + + + + ```bash theme={null} + python3 agent.py + ``` + + + + ```bash theme={null} + npx tsx agent.ts + ``` + + + +After running, check `utils.py`. You'll see defensive code handling empty lists and null users. Your agent autonomously: + +1. **Read** `utils.py` to understand the code +2. **Analyzed** the logic and identified edge cases that would crash +3. **Edited** the file to add proper error handling + +This is what makes the Agent SDK different: Claude executes tools directly instead of asking you to implement them. + + + If you see "API key not found", make sure you've set the `ANTHROPIC_API_KEY` environment variable in your `.env` file or shell environment. See the [full troubleshooting guide](/en/troubleshooting) for more help. + + +### Try other prompts + +Now that your agent is set up, try some different prompts: + +* `"Add docstrings to all functions in utils.py"` +* `"Add type hints to all functions in utils.py"` +* `"Create a README.md documenting the functions in utils.py"` + +### Customize your agent + +You can modify your agent's behavior by changing the options. Here are a few examples: + +**Add web search capability:** + + + ```python Python theme={null} + options = ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits" + ) + ``` + + ```typescript TypeScript hidelines={1,-1} theme={null} + const _ = { + options: { + allowedTools: ["Read", "Edit", "Glob", "WebSearch"], + permissionMode: "acceptEdits" + } + }; + ``` + + +**Give Claude a custom system prompt:** + + + ```python Python theme={null} + options = ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Glob"], + permission_mode="acceptEdits", + system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.", + ) + ``` + + ```typescript TypeScript hidelines={1,-1} theme={null} + const _ = { + options: { + allowedTools: ["Read", "Edit", "Glob"], + permissionMode: "acceptEdits", + systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines." + } + }; + ``` + + +**Run commands in the terminal:** + + + ```python Python theme={null} + options = ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits" + ) + ``` + + ```typescript TypeScript hidelines={1,-1} theme={null} + const _ = { + options: { + allowedTools: ["Read", "Edit", "Glob", "Bash"], + permissionMode: "acceptEdits" + } + }; + ``` + + +With `Bash` enabled, try: `"Write unit tests for utils.py, run them, and fix any failures"` + +## Key concepts + +**Tools** control what your agent can do: + +| Tools | What the agent can do | +| -------------------------------------- | ----------------------- | +| `Read`, `Glob`, `Grep` | Read-only analysis | +| `Read`, `Edit`, `Glob` | Analyze and modify code | +| `Read`, `Edit`, `Bash`, `Glob`, `Grep` | Full automation | + +**Permission modes** control how much human oversight you want: + +| Mode | Behavior | Use case | +| ------------------------ | ------------------------------------------------------------------------------- | ---------------------------------------- | +| `acceptEdits` | Auto-approves file edits and common filesystem commands, asks for other actions | Trusted development workflows | +| `dontAsk` | Denies anything not in `allowedTools` | Locked-down headless agents | +| `auto` (TypeScript only) | A model classifier approves or denies each tool call | Autonomous agents with safety guardrails | +| `bypassPermissions` | Runs every tool without prompts | Sandboxed CI, fully trusted environments | +| `default` | Requires a `canUseTool` callback to handle approval | Custom approval flows | + +The example above uses `acceptEdits` mode, which auto-approves file operations so the agent can run without interactive prompts. If you want to prompt users for approval, use `default` mode and provide a [`canUseTool` callback](/en/agent-sdk/user-input) that collects user input. For more control, see [Permissions](/en/agent-sdk/permissions). + +## Next steps + +Now that you've created your first agent, learn how to extend its capabilities and tailor it to your use case: + +* **[Permissions](/en/agent-sdk/permissions)**: control what your agent can do and when it needs approval +* **[Hooks](/en/agent-sdk/hooks)**: run custom code before or after tool calls +* **[Sessions](/en/agent-sdk/sessions)**: build multi-turn agents that maintain context +* **[MCP servers](/en/agent-sdk/mcp)**: connect to databases, browsers, APIs, and other external systems +* **[Hosting](/en/agent-sdk/hosting)**: deploy agents to Docker, cloud, and CI/CD +* **[Example agents](https://github.com/anthropics/claude-agent-sdk-demos)**: see complete examples: email assistant, research agent, and more diff --git a/content/en/docs/claude-code/agent-sdk/secure-deployment.md b/content/en/docs/claude-code/agent-sdk/secure-deployment.md new file mode 100644 index 000000000..605a1db37 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/secure-deployment.md @@ -0,0 +1,350 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Securely deploying AI agents + +> A guide to securing Claude Code and Agent SDK deployments with isolation, credential management, and network controls + +Claude Code and the Agent SDK are powerful tools that can execute code, access files, and interact with external services on your behalf. Like any tool with these capabilities, deploying them thoughtfully ensures you get the benefits while maintaining appropriate controls. + +Unlike traditional software that follows predetermined code paths, these tools generate their actions dynamically based on context and goals. This flexibility is what makes them useful, but it also means their behavior can be influenced by the content they process: files, webpages, or user input. This is sometimes called prompt injection. For example, if a repository's README contains unusual instructions, Claude Code might incorporate those into its actions in ways the operator didn't anticipate. This guide covers practical ways to reduce this risk. + +The good news is that securing an agent deployment doesn't require exotic infrastructure. The same principles that apply to running any semi-trusted code apply here: isolation, least privilege, and defense in depth. Claude Code includes several security features that help with common concerns, and this guide walks through these along with additional hardening options for those who need them. + +Not every deployment needs maximum security. A developer running Claude Code on their laptop has different requirements than a company processing customer data in a multi-tenant environment. This guide presents options ranging from Claude Code's built-in security features to hardened production architectures, so you can choose what fits your situation. + +## Threat model + +Agents can take unintended actions due to prompt injection (instructions embedded in content they process) or model error. Claude models are designed to resist this, and as analyzed in the [model card](https://www.anthropic.com/claude-opus-4-6-system-card), Claude Opus 4.6 is the most robust frontier model available. + +Defense in depth is still good practice though. For example, if an agent processes a malicious file that instructs it to send customer data to an external server, network controls can block that request entirely. + +## Built-in security features + +Claude Code includes several security features that address common concerns. See the [security documentation](/en/security) for full details. + +* **Permissions system**: Every tool and bash command can be configured to allow, block, or prompt the user for approval. Use glob patterns to create rules like "allow all npm commands" or "block any command with sudo". Organizations can set policies that apply across all users. See [permissions](/en/permissions). +* **Static analysis**: Before executing bash commands, Claude Code runs static analysis to identify potentially risky operations. Commands that modify system files or access sensitive directories are flagged and require explicit user approval. +* **Web search summarization**: Search results are summarized rather than passing raw content directly into the context, reducing the risk of prompt injection from malicious web content. +* **Sandbox mode**: Bash commands can run in a sandboxed environment that restricts filesystem and network access. See the [sandboxing documentation](/en/sandboxing) for details. + +## Security principles + +For deployments that require additional hardening beyond Claude Code's defaults, these principles guide the available options. + +### Security boundaries + +A security boundary separates components with different trust levels. For high-security deployments, you can place sensitive resources (like credentials) outside the boundary containing the agent. If something goes wrong in the agent's environment, resources outside that boundary remain protected. + +For example, rather than giving an agent direct access to an API key, you could run a proxy outside the agent's environment that injects the key into requests. The agent can make API calls, but it never sees the credential itself. This pattern is useful for multi-tenant deployments or when processing untrusted content. + +### Least privilege + +When needed, you can restrict the agent to only the capabilities required for its specific task: + +| Resource | Restriction options | +| ------------------- | ----------------------------------------------- | +| Filesystem | Mount only needed directories, prefer read-only | +| Network | Restrict to specific endpoints via proxy | +| Credentials | Inject via proxy rather than exposing directly | +| System capabilities | Drop Linux capabilities in containers | + +### Defense in depth + +For high-security environments, layering multiple controls provides additional protection. Options include: + +* Container isolation +* Network restrictions +* Filesystem controls +* Request validation at a proxy + +The right combination depends on your threat model and operational requirements. + +## Isolation technologies + +Different isolation technologies offer different tradeoffs between security strength, performance, and operational complexity. + + + In all of these configurations, Claude Code (or your Agent SDK application) runs inside the isolation boundary (the sandbox, container, or VM). The security controls described below restrict what the agent can access from within that boundary. + + +| Technology | Isolation strength | Performance overhead | Complexity | +| ----------------------- | ------------------------------ | -------------------- | ----------- | +| Sandbox runtime | Good (secure defaults) | Very low | Low | +| Containers (Docker) | Setup dependent | Low | Medium | +| gVisor | Excellent (with correct setup) | Medium/High | Medium | +| VMs (Firecracker, QEMU) | Excellent (with correct setup) | High | Medium/High | + +### Sandbox runtime + +For lightweight isolation without containers, [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime) enforces filesystem and network restrictions at the OS level. + +The main advantage is simplicity: no Docker configuration, container images, or networking setup required. The proxy and filesystem restrictions are built in. You provide a settings file specifying allowed domains and paths. + +**How it works:** + +* **Filesystem**: Uses OS primitives (`bubblewrap` on Linux, `sandbox-exec` on macOS) to restrict read/write access to configured paths +* **Network**: Removes network namespace (Linux) or uses Seatbelt profiles (macOS) to route network traffic through a built-in proxy +* **Configuration**: JSON-based allowlists for domains and filesystem paths + +**Setup:** + +```bash theme={null} +npm install @anthropic-ai/sandbox-runtime +``` + +Then create a configuration file specifying allowed paths and domains. + +**Security considerations:** + +1. **Same-host kernel**: Unlike VMs, sandboxed processes share the host kernel. A kernel vulnerability could theoretically enable escape. For some threat models this is acceptable, but if you need kernel-level isolation, use gVisor or a separate VM. + +2. **No TLS inspection**: The proxy allowlists domains but doesn't inspect encrypted traffic. If the agent has permissive credentials for an allowed domain, ensure it isn't possible to use that domain to trigger other network requests or to exfiltrate data. + +For many single-developer and CI/CD use cases, sandbox-runtime raises the bar significantly with minimal setup. The sections below cover containers and VMs for deployments requiring stronger isolation. + +### Containers + +Containers provide isolation through Linux namespaces. Each container has its own view of the filesystem, process tree, and network stack, while sharing the host kernel. + +A security-hardened container configuration might look like this: + +```bash theme={null} +docker run \ + --cap-drop ALL \ + --security-opt no-new-privileges \ + --security-opt seccomp=/path/to/seccomp-profile.json \ + --read-only \ + --tmpfs /tmp:rw,noexec,nosuid,size=100m \ + --tmpfs /home/agent:rw,noexec,nosuid,size=500m \ + --network none \ + --memory 2g \ + --cpus 2 \ + --pids-limit 100 \ + --user 1000:1000 \ + -v /path/to/code:/workspace:ro \ + -v /var/run/proxy.sock:/var/run/proxy.sock:ro \ + agent-image +``` + +Here's what each option does: + +| Option | Purpose | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--cap-drop ALL` | Removes Linux capabilities like `NET_ADMIN` and `SYS_ADMIN` that could enable privilege escalation | +| `--security-opt no-new-privileges` | Prevents processes from gaining privileges through setuid binaries | +| `--security-opt seccomp=...` | Restricts available syscalls; Docker's default blocks \~44, custom profiles can block more | +| `--read-only` | Makes the container's root filesystem immutable, preventing the agent from persisting changes | +| `--tmpfs /tmp:...` | Provides a writable temporary directory that's cleared when the container stops | +| `--network none` | Removes all network interfaces; the agent communicates through the mounted Unix socket below | +| `--memory 2g` | Limits memory usage to prevent resource exhaustion | +| `--pids-limit 100` | Limits process count to prevent fork bombs | +| `--user 1000:1000` | Runs as a non-root user | +| `-v ...:/workspace:ro` | Mounts code read-only so the agent can analyze but not modify it. **Avoid mounting sensitive host directories like `~/.ssh`, `~/.aws`, or `~/.config`** | +| `-v .../proxy.sock:...` | Mounts a Unix socket connected to a proxy running outside the container (see below) | + +**Unix socket architecture:** + +With `--network none`, the container has no network interfaces at all. The only way for the agent to reach the outside world is through the mounted Unix socket, which connects to a proxy running on the host. This proxy can enforce domain allowlists, inject credentials, and log all traffic. + +This is the same architecture used by [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime). Even if the agent is compromised via prompt injection, it cannot exfiltrate data to arbitrary servers. It can only communicate through the proxy, which controls what domains are reachable. For more details, see the [Claude Code sandboxing blog post](https://www.anthropic.com/engineering/claude-code-sandboxing). + +**Additional hardening options:** + +| Option | Purpose | +| ---------------- | -------------------------------------------------------------------------------------------------------------------- | +| `--userns-remap` | Maps container root to unprivileged host user; requires daemon configuration but limits damage from container escape | +| `--ipc private` | Isolates inter-process communication to prevent cross-container attacks | + +### gVisor + +Standard containers share the host kernel: when code inside a container makes a system call, it goes directly to the same kernel that runs the host. This means a kernel vulnerability could allow container escape. gVisor addresses this by intercepting system calls in userspace before they reach the host kernel, implementing its own compatibility layer that handles most syscalls without involving the real kernel. + +If an agent runs malicious code (perhaps due to prompt injection), that code runs in the container and could attempt kernel exploits. With gVisor, the attack surface is much smaller: the malicious code would need to exploit gVisor's userspace implementation first and would have limited access to the real kernel. + +To use gVisor with Docker, install the `runsc` runtime and configure the daemon: + +```json theme={null} +// /etc/docker/daemon.json +{ + "runtimes": { + "runsc": { + "path": "/usr/local/bin/runsc" + } + } +} +``` + +Then run containers with: + +```bash theme={null} +docker run --runtime=runsc agent-image +``` + +**Performance considerations:** + +| Workload | Overhead | +| --------------------- | -------------------------------------------------- | +| CPU-bound computation | \~0% (no syscall interception) | +| Simple syscalls | \~2× slower | +| File I/O intensive | Up to 10-200× slower for heavy open/close patterns | + +For multi-tenant environments or when processing untrusted content, the additional isolation is often worth the overhead. + +### Virtual machines + +VMs provide hardware-level isolation through CPU virtualization extensions. Each VM runs its own kernel, creating a strong boundary. A vulnerability in the guest kernel doesn't directly compromise the host. However, VMs aren't automatically "more secure" than alternatives like gVisor. VM security depends heavily on the hypervisor and device emulation code. + +Firecracker is designed for lightweight microVM isolation. It can boot VMs in under 125ms with less than 5 MiB memory overhead, stripping away unnecessary device emulation to reduce attack surface. + +With this approach, the agent VM has no external network interface. Instead, it communicates through `vsock` (virtual sockets). All traffic routes through vsock to a proxy on the host, which enforces allowlists and injects credentials before forwarding requests. + +### Cloud deployments + +For cloud deployments, you can combine any of the above isolation technologies with cloud-native network controls: + +1. Run agent containers in a private subnet with no internet gateway +2. Configure cloud firewall rules (AWS Security Groups, GCP VPC firewall) to block all egress except to your proxy +3. Run a proxy (such as [Envoy](https://www.envoyproxy.io/) with its `credential_injector` filter) that validates requests, enforces domain allowlists, injects credentials, and forwards to external APIs +4. Assign minimal IAM permissions to the agent's service account, routing sensitive access through the proxy where possible +5. Log all traffic at the proxy for audit purposes + +## Credential management + +Agents often need credentials to call APIs, access repositories, or interact with cloud services. The challenge is providing this access without exposing the credentials themselves. + +### The proxy pattern + +The recommended approach is to run a proxy outside the agent's security boundary that injects credentials into outgoing requests. The agent sends requests without credentials, the proxy adds them, and forwards the request to its destination. + +This pattern has several benefits: + +1. The agent never sees the actual credentials +2. The proxy can enforce an allowlist of permitted endpoints +3. The proxy can log all requests for auditing +4. Credentials are stored in one secure location rather than distributed to each agent + +### Configuring Claude Code to use a proxy + +Claude Code supports two methods for routing sampling requests through a proxy: + +**Option 1: ANTHROPIC\_BASE\_URL (simple but only for sampling API requests)** + +```bash theme={null} +export ANTHROPIC_BASE_URL="http://localhost:8080" +``` + +This tells Claude Code and the Agent SDK to send sampling requests to your proxy instead of the Claude API directly. Your proxy receives plaintext HTTP requests, can inspect and modify them (including injecting credentials), then forwards to the real API. + +**Option 2: HTTP\_PROXY / HTTPS\_PROXY (system-wide)** + +```bash theme={null} +export HTTP_PROXY="http://localhost:8080" +export HTTPS_PROXY="http://localhost:8080" +``` + +Claude Code and the Agent SDK respect these standard environment variables, routing all HTTP traffic through the proxy. For HTTPS, the proxy creates an encrypted CONNECT tunnel: it cannot see or modify request contents without TLS interception. + +### Implementing a proxy + +You can build your own proxy or use an existing one: + +* [Envoy Proxy](https://www.envoyproxy.io/): production-grade proxy with `credential_injector` filter for adding auth headers +* [mitmproxy](https://mitmproxy.org/): TLS-terminating proxy for inspecting and modifying HTTPS traffic +* [Squid](http://www.squid-cache.org/): caching proxy with access control lists +* [LiteLLM](https://github.com/BerriAI/litellm): LLM gateway with credential injection and rate limiting + +### Credentials for other services + +Beyond sampling from the Claude API, agents often need authenticated access to other services, such as git repositories, databases, and internal APIs. There are two main approaches: + +#### Custom tools + +Provide access through an MCP server or custom tool that routes requests to a service running outside the agent's security boundary. The agent calls the tool, but the actual authenticated request happens outside. The tool calls to a proxy which injects the credentials. + +For example, a git MCP server could accept commands from the agent but forward them to a git proxy running on the host, which adds authentication before contacting the remote repository. The agent never sees the credentials. + +Advantages: + +* **No TLS interception**: The external service makes authenticated requests directly +* **Credentials stay outside**: The agent only sees the tool interface, not the underlying credentials + +#### Traffic forwarding + +For Claude API calls, `ANTHROPIC_BASE_URL` lets you route requests to a proxy that can inspect and modify them in plaintext. But for other HTTPS services (GitHub, npm registries, internal APIs), the traffic is often encrypted end-to-end. Even if you route it through a proxy via `HTTP_PROXY`, the proxy only sees an opaque TLS tunnel and can't inject credentials. + +To modify HTTPS traffic to arbitrary services, without using a custom tool, you need a TLS-terminating proxy that decrypts traffic, inspects or modifies it, then re-encrypts it before forwarding. This requires: + +1. Running the proxy outside the agent's container +2. Installing the proxy's CA certificate in the agent's trust store (so the agent trusts the proxy's certificates) +3. Configuring `HTTP_PROXY`/`HTTPS_PROXY` to route traffic through the proxy + +This approach handles any HTTP-based service without writing custom tools, but adds complexity around certificate management. + +Note that not all programs respect `HTTP_PROXY`/`HTTPS_PROXY`. Most tools (curl, pip, npm, git) do, but some may bypass these variables and connect directly. For example, Node.js `fetch()` ignores these variables by default; in Node 24+ you can set `NODE_USE_ENV_PROXY=1` to enable support. For comprehensive coverage, you can use [proxychains](https://github.com/haad/proxychains) to intercept network calls, or configure iptables to redirect outbound traffic to a transparent proxy. + + + A **transparent proxy** intercepts traffic at the network level, so the client doesn't need to be configured to use it. Regular proxies require clients to explicitly connect and speak HTTP CONNECT or SOCKS. Transparent proxies (like Squid or mitmproxy in transparent mode) can handle raw redirected TCP connections. + + +Both approaches still require the TLS-terminating proxy and trusted CA certificate. They just ensure traffic actually reaches the proxy. + +## Filesystem configuration + +Filesystem controls determine what files the agent can read and write. + +### Read-only code mounting + +When the agent needs to analyze code but not modify it, mount the directory read-only: + +```bash theme={null} +docker run -v /path/to/code:/workspace:ro agent-image +``` + + + Even read-only access to a code directory can expose credentials. Common files to exclude or sanitize before mounting: + + | File | Risk | + | ------------------------------------------------------- | ------------------------------------- | + | `.env`, `.env.local` | API keys, database passwords, secrets | + | `~/.git-credentials` | Git passwords/tokens in plaintext | + | `~/.aws/credentials` | AWS access keys | + | `~/.config/gcloud/application_default_credentials.json` | Google Cloud ADC tokens | + | `~/.azure/` | Azure CLI credentials | + | `~/.docker/config.json` | Docker registry auth tokens | + | `~/.kube/config` | Kubernetes cluster credentials | + | `.npmrc`, `.pypirc` | Package registry tokens | + | `*-service-account.json` | GCP service account keys | + | `*.pem`, `*.key` | Private keys | + + Consider copying only the source files needed, or using `.dockerignore`-style filtering. + + +### Writable locations + +If the agent needs to write files, you have a few options depending on whether you want changes to persist: + +For ephemeral workspaces in containers, use `tmpfs` mounts that exist only in memory and are cleared when the container stops: + +```bash theme={null} +docker run \ + --read-only \ + --tmpfs /tmp:rw,noexec,nosuid,size=100m \ + --tmpfs /workspace:rw,noexec,size=500m \ + agent-image +``` + +If you want to review changes before persisting them, an overlay filesystem lets the agent write without modifying underlying files. Changes are stored in a separate layer you can inspect, apply, or discard. For fully persistent output, mount a dedicated volume but keep it separate from sensitive directories. + +## Further reading + +* [Claude Code security documentation](/en/security) +* [Hosting the Agent SDK](/en/agent-sdk/hosting) +* [Handling permissions](/en/agent-sdk/permissions) +* [Sandbox runtime](https://github.com/anthropic-experimental/sandbox-runtime) +* [The Lethal Trifecta for AI Agents](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) +* [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) +* [Docker Security Best Practices](https://docs.docker.com/engine/security/) +* [gVisor Documentation](https://gvisor.dev/docs/) +* [Firecracker Documentation](https://firecracker-microvm.github.io/) diff --git a/content/en/docs/claude-code/agent-sdk/sessions.md b/content/en/docs/claude-code/agent-sdk/sessions.md new file mode 100644 index 000000000..c51873457 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/sessions.md @@ -0,0 +1,322 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Work with sessions + +> How sessions persist agent conversation history, and when to use continue, resume, and fork to return to a prior run. + +A session is the conversation history the SDK accumulates while your agent works. It contains your prompt, every tool call the agent made, every tool result, and every response. The SDK writes it to disk automatically so you can return to it later. + +Returning to a session means the agent has full context from before: files it already read, analysis it already performed, decisions it already made. You can ask a follow-up question, recover from an interruption, or branch off to try a different approach. + + + Sessions persist the **conversation**, not the filesystem. To snapshot and revert file changes the agent made, use [file checkpointing](/en/agent-sdk/file-checkpointing). + + +This guide covers how to pick the right approach for your app, the SDK interfaces that track sessions automatically, how to capture session IDs and use `resume` and `fork` manually, and what to know about resuming sessions across hosts. + +## Choose an approach + +How much session handling you need depends on your application's shape. Session management comes into play when you send multiple prompts that should share context. Within a single `query()` call, the agent already takes as many turns as it needs, and permission prompts and `AskUserQuestion` are [handled in-loop](/en/agent-sdk/user-input) (they don't end the call). + +| What you're building | What to use | +| :-------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| One-shot task: single prompt, no follow-up | Nothing extra. One `query()` call handles it. | +| Multi-turn chat in one process | [`ClaudeSDKClient` (Python) or `continue: true` (TypeScript)](#automatic-session-management). The SDK tracks the session for you with no ID handling. | +| Pick up where you left off after a process restart | `continue_conversation=True` (Python) / `continue: true` (TypeScript). Resumes the most recent session in the directory, no ID needed. | +| Resume a specific past session (not the most recent) | Capture the session ID and pass it to `resume`. | +| Try an alternative approach without losing the original | Fork the session. | +| Stateless task, don't want anything written to disk (TypeScript only) | Set [`persistSession: false`](/en/agent-sdk/typescript#options). The session exists only in memory for the duration of the call. Python always persists to disk. | + +### Continue, resume, and fork + +Continue, resume, and fork are option fields you set on `query()` ([`ClaudeAgentOptions`](/en/agent-sdk/python#claude-agent-options) in Python, [`Options`](/en/agent-sdk/typescript#options) in TypeScript). + +**Continue** and **resume** both pick up an existing session and add to it. The difference is how they find that session: + +* **Continue** finds the most recent session in the current directory. You don't track anything. Works well when your app runs one conversation at a time. +* **Resume** takes a specific session ID. You track the ID. Required when you have multiple sessions (for example, one per user in a multi-user app) or want to return to one that isn't the most recent. + +**Fork** is different: it creates a new session that starts with a copy of the original's history. The original stays unchanged. Use fork to try a different direction while keeping the option to go back. + +## Automatic session management + +Both SDKs offer an interface that tracks session state for you across calls, so you don't pass IDs around manually. Use these for multi-turn conversations within a single process. + +### Python: `ClaudeSDKClient` + +[`ClaudeSDKClient`](/en/agent-sdk/python#claude-sdk-client) handles session IDs internally. Each call to `client.query()` automatically continues the same session. Call [`client.receive_response()`](/en/agent-sdk/python#claude-sdk-client) to iterate over the messages for the current query. The client must be used as an async context manager. + +This example runs two queries against the same `client`. The first asks the agent to analyze a module; the second asks it to refactor that module. Because both calls go through the same client instance, the second query has full context from the first without any explicit `resume` or session ID: + +```python Python theme={null} +import asyncio +from claude_agent_sdk import ( + ClaudeSDKClient, + ClaudeAgentOptions, + AssistantMessage, + ResultMessage, + TextBlock, +) + + +def print_response(message): + """Print only the human-readable parts of a message.""" + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(block.text) + elif isinstance(message, ResultMessage): + cost = ( + f"${message.total_cost_usd:.4f}" + if message.total_cost_usd is not None + else "N/A" + ) + print(f"[done: {message.subtype}, cost: {cost}]") + + +async def main(): + options = ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Glob", "Grep"], + ) + + async with ClaudeSDKClient(options=options) as client: + # First query: client captures the session ID internally + await client.query("Analyze the auth module") + async for message in client.receive_response(): + print_response(message) + + # Second query: automatically continues the same session + await client.query("Now refactor it to use JWT") + async for message in client.receive_response(): + print_response(message) + + +asyncio.run(main()) +``` + +See the [Python SDK reference](/en/agent-sdk/python#choosing-between-query-and-claude-sdk-client) for details on when to use `ClaudeSDKClient` vs the standalone `query()` function. + +### TypeScript: `continue: true` + +The stable TypeScript SDK (the `query()` function used throughout these docs, sometimes called V1) doesn't have a session-holding client object like Python's `ClaudeSDKClient`. Instead, pass `continue: true` on each subsequent `query()` call and the SDK picks up the most recent session in the current directory. No ID tracking required. + +This example makes two separate `query()` calls. The first creates a fresh session; the second sets `continue: true`, which tells the SDK to find and resume the most recent session on disk. The agent has full context from the first call: + +```typescript TypeScript theme={null} +import { query } from "@anthropic-ai/claude-agent-sdk"; + +// First query: creates a new session +for await (const message of query({ + prompt: "Analyze the auth module", + options: { allowedTools: ["Read", "Glob", "Grep"] } +})) { + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } +} + +// Second query: continue: true resumes the most recent session +for await (const message of query({ + prompt: "Now refactor it to use JWT", + options: { + continue: true, + allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"] + } +})) { + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } +} +``` + + + There's also a [V2 preview](/en/agent-sdk/typescript-v2-preview) of the TypeScript SDK that provides `createSession()` with a `send` / `stream` pattern, closer to Python's `ClaudeSDKClient` in feel. V2 is unstable and its APIs may change; the rest of this documentation uses the stable V1 `query()` function. + + +## Use session options with `query()` + +### Capture the session ID + +Resume and fork require a session ID. Read it from the `session_id` field on the result message ([`ResultMessage`](/en/agent-sdk/python#result-message) in Python, [`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message) in TypeScript), which is present on every result regardless of success or error. In TypeScript the ID is also available earlier as a direct field on the init `SystemMessage`; in Python it's nested inside `SystemMessage.data`. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + + async def main(): + session_id = None + + async for message in query( + prompt="Analyze the auth module and suggest improvements", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Glob", "Grep"], + ), + ): + if isinstance(message, ResultMessage): + session_id = message.session_id + if message.subtype == "success": + print(message.result) + + print(f"Session ID: {session_id}") + return session_id + + + session_id = asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + let sessionId: string | undefined; + + for await (const message of query({ + prompt: "Analyze the auth module and suggest improvements", + options: { allowedTools: ["Read", "Glob", "Grep"] } + })) { + if (message.type === "result") { + sessionId = message.session_id; + if (message.subtype === "success") { + console.log(message.result); + } + } + } + + console.log(`Session ID: ${sessionId}`); + ``` + + +### Resume by ID + +Pass a session ID to `resume` to return to that specific session. The agent picks up with full context from wherever the session left off. Common reasons to resume: + +* **Follow up on a completed task.** The agent already analyzed something; now you want it to act on that analysis without re-reading files. +* **Recover from a limit.** The first run ended with `error_max_turns` or `error_max_budget_usd` (see [Handle the result](/en/agent-sdk/agent-loop#handle-the-result)); resume with a higher limit. +* **Restart your process.** You captured the ID before shutdown and want to restore the conversation. + +This example resumes the session from [Capture the session ID](#capture-the-session-id) with a follow-up prompt. Because you're resuming, the agent already has the prior analysis in context: + + + ```python Python theme={null} + # Earlier session analyzed the code; now build on that analysis + async for message in query( + prompt="Now implement the refactoring you suggested", + options=ClaudeAgentOptions( + resume=session_id, + allowed_tools=["Read", "Edit", "Write", "Glob", "Grep"], + ), + ): + if isinstance(message, ResultMessage) and message.subtype == "success": + print(message.result) + ``` + + ```typescript TypeScript theme={null} + // Earlier session analyzed the code; now build on that analysis + for await (const message of query({ + prompt: "Now implement the refactoring you suggested", + options: { + resume: sessionId, + allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"] + } + })) { + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } + } + ``` + + + + If a `resume` call returns a fresh session instead of the expected history, the most common cause is a mismatched `cwd`. Sessions are stored under `~/.claude/projects//*.jsonl`, where `` is the absolute working directory with every non-alphanumeric character replaced by `-` (so `/Users/me/proj` becomes `-Users-me-proj`). If your resume call runs from a different directory, the SDK looks in the wrong place. The session file also needs to exist on the current machine. + + +### Fork to explore alternatives + +Forking creates a new session that starts with a copy of the original's history but diverges from that point. The fork gets its own session ID; the original's ID and history stay unchanged. You end up with two independent sessions you can resume separately. + + + Forking branches the conversation history, not the filesystem. If a forked agent edits files, those changes are real and visible to any session working in the same directory. To branch and revert file changes, use [file checkpointing](/en/agent-sdk/file-checkpointing). + + +This example builds on [Capture the session ID](#capture-the-session-id): you've already analyzed an auth module in `session_id` and want to explore OAuth2 without losing the JWT-focused thread. The first block forks the session and captures the fork's ID (`forked_id`); the second block resumes the original `session_id` to continue down the JWT path. You now have two session IDs pointing at two separate histories: + + + ```python Python theme={null} + # Fork: branch from session_id into a new session + forked_id = None + async for message in query( + prompt="Instead of JWT, implement OAuth2 for the auth module", + options=ClaudeAgentOptions( + resume=session_id, + fork_session=True, + ), + ): + if isinstance(message, ResultMessage): + forked_id = message.session_id # The fork's ID, distinct from session_id + if message.subtype == "success": + print(message.result) + + print(f"Forked session: {forked_id}") + + # Original session is untouched; resuming it continues the JWT thread + async for message in query( + prompt="Continue with the JWT approach", + options=ClaudeAgentOptions(resume=session_id), + ): + if isinstance(message, ResultMessage) and message.subtype == "success": + print(message.result) + ``` + + ```typescript TypeScript theme={null} + // Fork: branch from sessionId into a new session + let forkedId: string | undefined; + + for await (const message of query({ + prompt: "Instead of JWT, implement OAuth2 for the auth module", + options: { + resume: sessionId, + forkSession: true + } + })) { + if (message.type === "system" && message.subtype === "init") { + forkedId = message.session_id; // The fork's ID, distinct from sessionId + } + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } + } + + console.log(`Forked session: ${forkedId}`); + + // Original session is untouched; resuming it continues the JWT thread + for await (const message of query({ + prompt: "Continue with the JWT approach", + options: { resume: sessionId } + })) { + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } + } + ``` + + +## Resume across hosts + +Session files are local to the machine that created them. To resume a session on a different host (CI workers, ephemeral containers, serverless), you have two options: + +* **Move the session file.** Persist `~/.claude/projects//.jsonl` from the first run and restore it to the same path on the new host before calling `resume`. The `cwd` must match. +* **Don't rely on session resume.** Capture the results you need (analysis output, decisions, file diffs) as application state and pass them into a fresh session's prompt. This is often more robust than shipping transcript files around. + +Both SDKs expose functions for enumerating sessions on disk and reading their messages: [`listSessions()`](/en/agent-sdk/typescript#list-sessions) and [`getSessionMessages()`](/en/agent-sdk/typescript#get-session-messages) in TypeScript, [`list_sessions()`](/en/agent-sdk/python#list-sessions) and [`get_session_messages()`](/en/agent-sdk/python#get-session-messages) in Python. Use them to build custom session pickers, cleanup logic, or transcript viewers. + +Both SDKs also expose functions for looking up and mutating individual sessions: [`get_session_info()`](/en/agent-sdk/python#get-session-info), [`rename_session()`](/en/agent-sdk/python#rename-session), and [`tag_session()`](/en/agent-sdk/python#tag-session) in Python, and [`getSessionInfo()`](/en/agent-sdk/typescript#get-session-info), [`renameSession()`](/en/agent-sdk/typescript#rename-session), and [`tagSession()`](/en/agent-sdk/typescript#tag-session) in TypeScript. Use them to organize sessions by tag or give them human-readable titles. + +## Related resources + +* [How the agent loop works](/en/agent-sdk/agent-loop): Understand turns, messages, and context accumulation within a session +* [File checkpointing](/en/agent-sdk/file-checkpointing): Track and revert file changes across sessions +* [Python `ClaudeAgentOptions`](/en/agent-sdk/python#claude-agent-options): Full session option reference for Python +* [TypeScript `Options`](/en/agent-sdk/typescript#options): Full session option reference for TypeScript diff --git a/content/en/docs/claude-code/agent-sdk/skills.md b/content/en/docs/claude-code/agent-sdk/skills.md new file mode 100644 index 000000000..d547e651f --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/skills.md @@ -0,0 +1,296 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Agent Skills in the SDK + +> Extend Claude with specialized capabilities using Agent Skills in the Claude Agent SDK + +## Overview + +Agent Skills extend Claude with specialized capabilities that Claude autonomously invokes when relevant. Skills are packaged as `SKILL.md` files containing instructions, descriptions, and optional supporting resources. + +For comprehensive information about Skills, including benefits, architecture, and authoring guidelines, see the [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview). + +## How Skills Work with the SDK + +When using the Claude Agent SDK, Skills are: + +1. **Defined as filesystem artifacts**: Created as `SKILL.md` files in specific directories (`.claude/skills/`) +2. **Loaded from filesystem**: Skills are loaded from configured filesystem locations. You must specify `settingSources` (TypeScript) or `setting_sources` (Python) to load Skills from the filesystem +3. **Automatically discovered**: Once filesystem settings are loaded, Skill metadata is discovered at startup from user and project directories; full content loaded when triggered +4. **Model-invoked**: Claude autonomously chooses when to use them based on context +5. **Enabled via allowed\_tools**: Add `"Skill"` to your `allowed_tools` to enable Skills + +Unlike subagents (which can be defined programmatically), Skills must be created as filesystem artifacts. The SDK does not provide a programmatic API for registering Skills. + + + **Default behavior**: By default, the SDK does not load any filesystem settings. To use Skills, you must explicitly configure `settingSources: ['user', 'project']` (TypeScript) or `setting_sources=["user", "project"]` (Python) in your options. + + +## Using Skills with the SDK + +To use Skills with the SDK, you need to: + +1. Include `"Skill"` in your `allowed_tools` configuration +2. Configure `settingSources`/`setting_sources` to load Skills from the filesystem + +Once configured, Claude automatically discovers Skills from the specified directories and invokes them when relevant to the user's request. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions + + + async def main(): + options = ClaudeAgentOptions( + cwd="/path/to/project", # Project with .claude/skills/ + setting_sources=["user", "project"], # Load Skills from filesystem + allowed_tools=["Skill", "Read", "Write", "Bash"], # Enable Skill tool + ) + + async for message in query( + prompt="Help me process this PDF document", options=options + ): + print(message) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Help me process this PDF document", + options: { + cwd: "/path/to/project", // Project with .claude/skills/ + settingSources: ["user", "project"], // Load Skills from filesystem + allowedTools: ["Skill", "Read", "Write", "Bash"] // Enable Skill tool + } + })) { + console.log(message); + } + ``` + + +## Skill Locations + +Skills are loaded from filesystem directories based on your `settingSources`/`setting_sources` configuration: + +* **Project Skills** (`.claude/skills/`): Shared with your team via git - loaded when `setting_sources` includes `"project"` +* **User Skills** (`~/.claude/skills/`): Personal Skills across all projects - loaded when `setting_sources` includes `"user"` +* **Plugin Skills**: Bundled with installed Claude Code plugins + +## Creating Skills + +Skills are defined as directories containing a `SKILL.md` file with YAML frontmatter and Markdown content. The `description` field determines when Claude invokes your Skill. + +**Example directory structure**: + +```bash theme={null} +.claude/skills/processing-pdfs/ +└── SKILL.md +``` + +For complete guidance on creating Skills, including SKILL.md structure, multi-file Skills, and examples, see: + +* [Agent Skills in Claude Code](/en/skills): Complete guide with examples +* [Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): Authoring guidelines and naming conventions + +## Tool Restrictions + + + The `allowed-tools` frontmatter field in SKILL.md is only supported when using Claude Code CLI directly. **It does not apply when using Skills through the SDK**. + + When using the SDK, control tool access through the main `allowedTools` option in your query configuration. + + +To control tool access for Skills in SDK applications, use `allowedTools` to pre-approve specific tools. Without a `canUseTool` callback, anything not in the list is denied: + + + Import statements from the first example are assumed in the following code snippets. + + + + ```python Python theme={null} + options = ClaudeAgentOptions( + setting_sources=["user", "project"], # Load Skills from filesystem + allowed_tools=["Skill", "Read", "Grep", "Glob"], + ) + + async for message in query(prompt="Analyze the codebase structure", options=options): + print(message) + ``` + + ```typescript TypeScript theme={null} + for await (const message of query({ + prompt: "Analyze the codebase structure", + options: { + settingSources: ["user", "project"], // Load Skills from filesystem + allowedTools: ["Skill", "Read", "Grep", "Glob"], + permissionMode: "dontAsk" // Deny anything not in allowedTools + } + })) { + console.log(message); + } + ``` + + +## Discovering Available Skills + +To see which Skills are available in your SDK application, simply ask Claude: + + + ```python Python theme={null} + options = ClaudeAgentOptions( + setting_sources=["user", "project"], # Load Skills from filesystem + allowed_tools=["Skill"], + ) + + async for message in query(prompt="What Skills are available?", options=options): + print(message) + ``` + + ```typescript TypeScript theme={null} + for await (const message of query({ + prompt: "What Skills are available?", + options: { + settingSources: ["user", "project"], // Load Skills from filesystem + allowedTools: ["Skill"] + } + })) { + console.log(message); + } + ``` + + +Claude will list the available Skills based on your current working directory and installed plugins. + +## Testing Skills + +Test Skills by asking questions that match their descriptions: + + + ```python Python theme={null} + options = ClaudeAgentOptions( + cwd="/path/to/project", + setting_sources=["user", "project"], # Load Skills from filesystem + allowed_tools=["Skill", "Read", "Bash"], + ) + + async for message in query(prompt="Extract text from invoice.pdf", options=options): + print(message) + ``` + + ```typescript TypeScript theme={null} + for await (const message of query({ + prompt: "Extract text from invoice.pdf", + options: { + cwd: "/path/to/project", + settingSources: ["user", "project"], // Load Skills from filesystem + allowedTools: ["Skill", "Read", "Bash"] + } + })) { + console.log(message); + } + ``` + + +Claude automatically invokes the relevant Skill if the description matches your request. + +## Troubleshooting + +### Skills Not Found + +**Check settingSources configuration**: Skills are only loaded when you explicitly configure `settingSources`/`setting_sources`. This is the most common issue: + + + ```python Python theme={null} + # Wrong - Skills won't be loaded + options = ClaudeAgentOptions(allowed_tools=["Skill"]) + + # Correct - Skills will be loaded + options = ClaudeAgentOptions( + setting_sources=["user", "project"], # Required to load Skills + allowed_tools=["Skill"], + ) + ``` + + ```typescript TypeScript theme={null} + // Wrong - Skills won't be loaded + const options = { + allowedTools: ["Skill"] + }; + + // Correct - Skills will be loaded + const options = { + settingSources: ["user", "project"], // Required to load Skills + allowedTools: ["Skill"] + }; + ``` + + +For more details on `settingSources`/`setting_sources`, see the [TypeScript SDK reference](/en/agent-sdk/typescript#setting-source) or [Python SDK reference](/en/agent-sdk/python#setting-source). + +**Check working directory**: The SDK loads Skills relative to the `cwd` option. Ensure it points to a directory containing `.claude/skills/`: + + + ```python Python theme={null} + # Ensure your cwd points to the directory containing .claude/skills/ + options = ClaudeAgentOptions( + cwd="/path/to/project", # Must contain .claude/skills/ + setting_sources=["user", "project"], # Required to load Skills + allowed_tools=["Skill"], + ) + ``` + + ```typescript TypeScript theme={null} + // Ensure your cwd points to the directory containing .claude/skills/ + const options = { + cwd: "/path/to/project", // Must contain .claude/skills/ + settingSources: ["user", "project"], // Required to load Skills + allowedTools: ["Skill"] + }; + ``` + + +See the "Using Skills with the SDK" section above for the complete pattern. + +**Verify filesystem location**: + +```bash theme={null} +# Check project Skills +ls .claude/skills/*/SKILL.md + +# Check personal Skills +ls ~/.claude/skills/*/SKILL.md +``` + +### Skill Not Being Used + +**Check the Skill tool is enabled**: Confirm `"Skill"` is in your `allowedTools`. + +**Check the description**: Ensure it's specific and includes relevant keywords. See [Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#writing-effective-descriptions) for guidance on writing effective descriptions. + +### Additional Troubleshooting + +For general Skills troubleshooting (YAML syntax, debugging, etc.), see the [Claude Code Skills troubleshooting section](/en/skills#troubleshooting). + +## Related Documentation + +### Skills Guides + +* [Agent Skills in Claude Code](/en/skills): Complete Skills guide with creation, examples, and troubleshooting +* [Agent Skills Overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview): Conceptual overview, benefits, and architecture +* [Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): Authoring guidelines for effective Skills +* [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction): Example Skills and templates + +### SDK Resources + +* [Subagents in the SDK](/en/agent-sdk/subagents): Similar filesystem-based agents with programmatic options +* [Slash Commands in the SDK](/en/agent-sdk/slash-commands): User-invoked commands +* [SDK Overview](/en/agent-sdk/overview): General SDK concepts +* [TypeScript SDK Reference](/en/agent-sdk/typescript): Complete API documentation +* [Python SDK Reference](/en/agent-sdk/python): Complete API documentation diff --git a/content/en/docs/claude-code/agent-sdk/slash-commands.md b/content/en/docs/claude-code/agent-sdk/slash-commands.md new file mode 100644 index 000000000..ffa9c91da --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/slash-commands.md @@ -0,0 +1,477 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Slash Commands in the SDK + +> Learn how to use slash commands to control Claude Code sessions through the SDK + +Slash commands provide a way to control Claude Code sessions with special commands that start with `/`. These commands can be sent through the SDK to perform actions like clearing conversation history, compacting messages, or getting help. + +## Discovering Available Slash Commands + +The Claude Agent SDK provides information about available slash commands in the system initialization message. Access this information when your session starts: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Hello Claude", + options: { maxTurns: 1 } + })) { + if (message.type === "system" && message.subtype === "init") { + console.log("Available slash commands:", message.slash_commands); + // Example output: ["/compact", "/clear", "/help"] + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage + + + async def main(): + async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)): + if isinstance(message, SystemMessage) and message.subtype == "init": + print("Available slash commands:", message.data["slash_commands"]) + # Example output: ["/compact", "/clear", "/help"] + + + asyncio.run(main()) + ``` + + +## Sending Slash Commands + +Send slash commands by including them in your prompt string, just like regular text: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Send a slash command + for await (const message of query({ + prompt: "/compact", + options: { maxTurns: 1 } + })) { + if (message.type === "result") { + console.log("Command executed:", message.result); + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + + async def main(): + # Send a slash command + async for message in query(prompt="/compact", options=ClaudeAgentOptions(max_turns=1)): + if isinstance(message, ResultMessage): + print("Command executed:", message.result) + + + asyncio.run(main()) + ``` + + +## Common Slash Commands + +### `/compact` - Compact Conversation History + +The `/compact` command reduces the size of your conversation history by summarizing older messages while preserving important context: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "/compact", + options: { maxTurns: 1 } + })) { + if (message.type === "system" && message.subtype === "compact_boundary") { + console.log("Compaction completed"); + console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens); + console.log("Trigger:", message.compact_metadata.trigger); + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage + + + async def main(): + async for message in query(prompt="/compact", options=ClaudeAgentOptions(max_turns=1)): + if isinstance(message, SystemMessage) and message.subtype == "compact_boundary": + print("Compaction completed") + print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"]) + print("Trigger:", message.data["compact_metadata"]["trigger"]) + + + asyncio.run(main()) + ``` + + +### `/clear` - Clear Conversation + +The `/clear` command starts a fresh conversation by clearing all previous history: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Clear conversation and start fresh + for await (const message of query({ + prompt: "/clear", + options: { maxTurns: 1 } + })) { + if (message.type === "system" && message.subtype === "init") { + console.log("Conversation cleared, new session started"); + console.log("Session ID:", message.session_id); + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage + + + async def main(): + # Clear conversation and start fresh + async for message in query(prompt="/clear", options=ClaudeAgentOptions(max_turns=1)): + if isinstance(message, SystemMessage) and message.subtype == "init": + print("Conversation cleared, new session started") + print("Session ID:", message.data["session_id"]) + + + asyncio.run(main()) + ``` + + +## Creating Custom Slash Commands + +In addition to using built-in slash commands, you can create your own custom commands that are available through the SDK. Custom commands are defined as markdown files in specific directories, similar to how subagents are configured. + + + The `.claude/commands/` directory is the legacy format. The recommended format is `.claude/skills//SKILL.md`, which supports the same slash-command invocation (`/name`) plus autonomous invocation by Claude. See [Skills](/en/agent-sdk/skills) for the current format. The CLI continues to support both formats, and the examples below remain accurate for `.claude/commands/`. + + +### File Locations + +Custom slash commands are stored in designated directories based on their scope: + +* **Project commands**: `.claude/commands/` - Available only in the current project (legacy; prefer `.claude/skills/`) +* **Personal commands**: `~/.claude/commands/` - Available across all your projects (legacy; prefer `~/.claude/skills/`) + +### File Format + +Each custom command is a markdown file where: + +* The filename (without `.md` extension) becomes the command name +* The file content defines what the command does +* Optional YAML frontmatter provides configuration + +#### Basic Example + +Create `.claude/commands/refactor.md`: + +```markdown theme={null} +Refactor the selected code to improve readability and maintainability. +Focus on clean code principles and best practices. +``` + +This creates the `/refactor` command that you can use through the SDK. + +#### With Frontmatter + +Create `.claude/commands/security-check.md`: + +```markdown theme={null} +--- +allowed-tools: Read, Grep, Glob +description: Run security vulnerability scan +model: claude-opus-4-6 +--- + +Analyze the codebase for security vulnerabilities including: +- SQL injection risks +- XSS vulnerabilities +- Exposed credentials +- Insecure configurations +``` + +### Using Custom Commands in the SDK + +Once defined in the filesystem, custom commands are automatically available through the SDK: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Use a custom command + for await (const message of query({ + prompt: "/refactor src/auth/login.ts", + options: { maxTurns: 3 } + })) { + if (message.type === "assistant") { + console.log("Refactoring suggestions:", message.message); + } + } + + // Custom commands appear in the slash_commands list + for await (const message of query({ + prompt: "Hello", + options: { maxTurns: 1 } + })) { + if (message.type === "system" && message.subtype === "init") { + // Will include both built-in and custom commands + console.log("Available commands:", message.slash_commands); + // Example: ["/compact", "/clear", "/help", "/refactor", "/security-check"] + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, SystemMessage + + + async def main(): + # Use a custom command + async for message in query( + prompt="/refactor src/auth/login.py", options=ClaudeAgentOptions(max_turns=3) + ): + if isinstance(message, AssistantMessage): + for block in message.content: + if hasattr(block, "text"): + print("Refactoring suggestions:", block.text) + + # Custom commands appear in the slash_commands list + async for message in query(prompt="Hello", options=ClaudeAgentOptions(max_turns=1)): + if isinstance(message, SystemMessage) and message.subtype == "init": + # Will include both built-in and custom commands + print("Available commands:", message.data["slash_commands"]) + # Example: ["/compact", "/clear", "/help", "/refactor", "/security-check"] + + + asyncio.run(main()) + ``` + + +### Advanced Features + +#### Arguments and Placeholders + +Custom commands support dynamic arguments using placeholders: + +Create `.claude/commands/fix-issue.md`: + +```markdown theme={null} +--- +argument-hint: [issue-number] [priority] +description: Fix a GitHub issue +--- + +Fix issue #$1 with priority $2. +Check the issue description and implement the necessary changes. +``` + +Use in SDK: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Pass arguments to custom command + for await (const message of query({ + prompt: "/fix-issue 123 high", + options: { maxTurns: 5 } + })) { + // Command will process with $1="123" and $2="high" + if (message.type === "result") { + console.log("Issue fixed:", message.result); + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + + async def main(): + # Pass arguments to custom command + async for message in query(prompt="/fix-issue 123 high", options=ClaudeAgentOptions(max_turns=5)): + # Command will process with $1="123" and $2="high" + if isinstance(message, ResultMessage): + print("Issue fixed:", message.result) + + + asyncio.run(main()) + ``` + + +#### Bash Command Execution + +Custom commands can execute bash commands and include their output: + +Create `.claude/commands/git-commit.md`: + +```markdown theme={null} +--- +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*) +description: Create a git commit +--- + +## Context + +- Current status: !`git status` +- Current diff: !`git diff HEAD` + +## Task + +Create a git commit with appropriate message based on the changes. +``` + +#### File References + +Include file contents using the `@` prefix: + +Create `.claude/commands/review-config.md`: + +```markdown theme={null} +--- +description: Review configuration files +--- + +Review the following configuration files for issues: +- Package config: @package.json +- TypeScript config: @tsconfig.json +- Environment config: @.env + +Check for security issues, outdated dependencies, and misconfigurations. +``` + +### Organization with Namespacing + +Organize commands in subdirectories for better structure: + +```bash theme={null} +.claude/commands/ +├── frontend/ +│ ├── component.md # Creates /component (project:frontend) +│ └── style-check.md # Creates /style-check (project:frontend) +├── backend/ +│ ├── api-test.md # Creates /api-test (project:backend) +│ └── db-migrate.md # Creates /db-migrate (project:backend) +└── review.md # Creates /review (project) +``` + +The subdirectory appears in the command description but doesn't affect the command name itself. + +### Practical Examples + +#### Code Review Command + +Create `.claude/commands/code-review.md`: + +```markdown theme={null} +--- +allowed-tools: Read, Grep, Glob, Bash(git diff:*) +description: Comprehensive code review +--- + +## Changed Files +!`git diff --name-only HEAD~1` + +## Detailed Changes +!`git diff HEAD~1` + +## Review Checklist + +Review the above changes for: +1. Code quality and readability +2. Security vulnerabilities +3. Performance implications +4. Test coverage +5. Documentation completeness + +Provide specific, actionable feedback organized by priority. +``` + +#### Test Runner Command + +Create `.claude/commands/test.md`: + +```markdown theme={null} +--- +allowed-tools: Bash, Read, Edit +argument-hint: [test-pattern] +description: Run tests with optional pattern +--- + +Run tests matching pattern: $ARGUMENTS + +1. Detect the test framework (Jest, pytest, etc.) +2. Run tests with the provided pattern +3. If tests fail, analyze and fix them +4. Re-run to verify fixes +``` + +Use these commands through the SDK: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Run code review + for await (const message of query({ + prompt: "/code-review", + options: { maxTurns: 3 } + })) { + // Process review feedback + } + + // Run specific tests + for await (const message of query({ + prompt: "/test auth", + options: { maxTurns: 5 } + })) { + // Handle test results + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions + + + async def main(): + # Run code review + async for message in query(prompt="/code-review", options=ClaudeAgentOptions(max_turns=3)): + # Process review feedback + pass + + # Run specific tests + async for message in query(prompt="/test auth", options=ClaudeAgentOptions(max_turns=5)): + # Handle test results + pass + + + asyncio.run(main()) + ``` + + +## See Also + +* [Slash Commands](/en/skills) - Complete slash command documentation +* [Subagents in the SDK](/en/agent-sdk/subagents) - Similar filesystem-based configuration for subagents +* [TypeScript SDK reference](/en/agent-sdk/typescript) - Complete API documentation +* [SDK overview](/en/agent-sdk/overview) - General SDK concepts +* [CLI reference](/en/cli-reference) - Command-line interface diff --git a/content/en/docs/claude-code/agent-sdk/streaming-output.md b/content/en/docs/claude-code/agent-sdk/streaming-output.md new file mode 100644 index 000000000..b0a0e7f6d --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/streaming-output.md @@ -0,0 +1,396 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Stream responses in real-time + +> Get real-time responses from the Agent SDK as text and tool calls stream in + +By default, the Agent SDK yields complete `AssistantMessage` objects after Claude finishes generating each response. To receive incremental updates as text and tool calls are generated, enable partial message streaming by setting `include_partial_messages` (Python) or `includePartialMessages` (TypeScript) to `true` in your options. + + + This page covers output streaming (receiving tokens in real-time). For input modes (how you send messages), see [Send messages to agents](/en/agent-sdk/streaming-vs-single-mode). You can also [stream responses using the Agent SDK via the CLI](/en/headless). + + +## Enable streaming output + +To enable streaming, set `include_partial_messages` (Python) or `includePartialMessages` (TypeScript) to `true` in your options. This causes the SDK to yield `StreamEvent` messages containing raw API events as they arrive, in addition to the usual `AssistantMessage` and `ResultMessage`. + +Your code then needs to: + +1. Check each message's type to distinguish `StreamEvent` from other message types +2. For `StreamEvent`, extract the `event` field and check its `type` +3. Look for `content_block_delta` events where `delta.type` is `text_delta`, which contain the actual text chunks + +The example below enables streaming and prints text chunks as they arrive. Notice the nested type checks: first for `StreamEvent`, then for `content_block_delta`, then for `text_delta`: + + + ```python Python theme={null} + from claude_agent_sdk import query, ClaudeAgentOptions + from claude_agent_sdk.types import StreamEvent + import asyncio + + + async def stream_response(): + options = ClaudeAgentOptions( + include_partial_messages=True, + allowed_tools=["Bash", "Read"], + ) + + async for message in query(prompt="List the files in my project", options=options): + if isinstance(message, StreamEvent): + event = message.event + if event.get("type") == "content_block_delta": + delta = event.get("delta", {}) + if delta.get("type") == "text_delta": + print(delta.get("text", ""), end="", flush=True) + + + asyncio.run(stream_response()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "List the files in my project", + options: { + includePartialMessages: true, + allowedTools: ["Bash", "Read"] + } + })) { + if (message.type === "stream_event") { + const event = message.event; + if (event.type === "content_block_delta") { + if (event.delta.type === "text_delta") { + process.stdout.write(event.delta.text); + } + } + } + } + ``` + + +## StreamEvent reference + +When partial messages are enabled, you receive raw Claude API streaming events wrapped in an object. The type has different names in each SDK: + +* **Python**: `StreamEvent` (import from `claude_agent_sdk.types`) +* **TypeScript**: `SDKPartialAssistantMessage` with `type: 'stream_event'` + +Both contain raw Claude API events, not accumulated text. You need to extract and accumulate text deltas yourself. Here's the structure of each type: + + + ```python Python theme={null} + @dataclass + class StreamEvent: + uuid: str # Unique identifier for this event + session_id: str # Session identifier + event: dict[str, Any] # The raw Claude API stream event + parent_tool_use_id: str | None # Parent tool ID if from a subagent + ``` + + ```typescript TypeScript theme={null} + type SDKPartialAssistantMessage = { + type: "stream_event"; + event: RawMessageStreamEvent; // From Anthropic SDK + parent_tool_use_id: string | null; + uuid: UUID; + session_id: string; + }; + ``` + + +The `event` field contains the raw streaming event from the [Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types). Common event types include: + +| Event Type | Description | +| :-------------------- | :---------------------------------------------- | +| `message_start` | Start of a new message | +| `content_block_start` | Start of a new content block (text or tool use) | +| `content_block_delta` | Incremental update to content | +| `content_block_stop` | End of a content block | +| `message_delta` | Message-level updates (stop reason, usage) | +| `message_stop` | End of the message | + +## Message flow + +With partial messages enabled, you receive messages in this order: + +```text theme={null} +StreamEvent (message_start) +StreamEvent (content_block_start) - text block +StreamEvent (content_block_delta) - text chunks... +StreamEvent (content_block_stop) +StreamEvent (content_block_start) - tool_use block +StreamEvent (content_block_delta) - tool input chunks... +StreamEvent (content_block_stop) +StreamEvent (message_delta) +StreamEvent (message_stop) +AssistantMessage - complete message with all content +... tool executes ... +... more streaming events for next turn ... +ResultMessage - final result +``` + +Without partial messages enabled (`include_partial_messages` in Python, `includePartialMessages` in TypeScript), you receive all message types except `StreamEvent`. Common types include `SystemMessage` (session initialization), `AssistantMessage` (complete responses), `ResultMessage` (final result), and a compact boundary message indicating when conversation history was compacted (`SDKCompactBoundaryMessage` in TypeScript; `SystemMessage` with subtype `"compact_boundary"` in Python). + +## Stream text responses + +To display text as it's generated, look for `content_block_delta` events where `delta.type` is `text_delta`. These contain the incremental text chunks. The example below prints each chunk as it arrives: + + + ```python Python theme={null} + from claude_agent_sdk import query, ClaudeAgentOptions + from claude_agent_sdk.types import StreamEvent + import asyncio + + + async def stream_text(): + options = ClaudeAgentOptions(include_partial_messages=True) + + async for message in query(prompt="Explain how databases work", options=options): + if isinstance(message, StreamEvent): + event = message.event + if event.get("type") == "content_block_delta": + delta = event.get("delta", {}) + if delta.get("type") == "text_delta": + # Print each text chunk as it arrives + print(delta.get("text", ""), end="", flush=True) + + print() # Final newline + + + asyncio.run(stream_text()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Explain how databases work", + options: { includePartialMessages: true } + })) { + if (message.type === "stream_event") { + const event = message.event; + if (event.type === "content_block_delta" && event.delta.type === "text_delta") { + process.stdout.write(event.delta.text); + } + } + } + + console.log(); // Final newline + ``` + + +## Stream tool calls + +Tool calls also stream incrementally. You can track when tools start, receive their input as it's generated, and see when they complete. The example below tracks the current tool being called and accumulates the JSON input as it streams in. It uses three event types: + +* `content_block_start`: tool begins +* `content_block_delta` with `input_json_delta`: input chunks arrive +* `content_block_stop`: tool call complete + + + ```python Python theme={null} + from claude_agent_sdk import query, ClaudeAgentOptions + from claude_agent_sdk.types import StreamEvent + import asyncio + + + async def stream_tool_calls(): + options = ClaudeAgentOptions( + include_partial_messages=True, + allowed_tools=["Read", "Bash"], + ) + + # Track the current tool and accumulate its input JSON + current_tool = None + tool_input = "" + + async for message in query(prompt="Read the README.md file", options=options): + if isinstance(message, StreamEvent): + event = message.event + event_type = event.get("type") + + if event_type == "content_block_start": + # New tool call is starting + content_block = event.get("content_block", {}) + if content_block.get("type") == "tool_use": + current_tool = content_block.get("name") + tool_input = "" + print(f"Starting tool: {current_tool}") + + elif event_type == "content_block_delta": + delta = event.get("delta", {}) + if delta.get("type") == "input_json_delta": + # Accumulate JSON input as it streams in + chunk = delta.get("partial_json", "") + tool_input += chunk + print(f" Input chunk: {chunk}") + + elif event_type == "content_block_stop": + # Tool call complete - show final input + if current_tool: + print(f"Tool {current_tool} called with: {tool_input}") + current_tool = None + + + asyncio.run(stream_tool_calls()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Track the current tool and accumulate its input JSON + let currentTool: string | null = null; + let toolInput = ""; + + for await (const message of query({ + prompt: "Read the README.md file", + options: { + includePartialMessages: true, + allowedTools: ["Read", "Bash"] + } + })) { + if (message.type === "stream_event") { + const event = message.event; + + if (event.type === "content_block_start") { + // New tool call is starting + if (event.content_block.type === "tool_use") { + currentTool = event.content_block.name; + toolInput = ""; + console.log(`Starting tool: ${currentTool}`); + } + } else if (event.type === "content_block_delta") { + if (event.delta.type === "input_json_delta") { + // Accumulate JSON input as it streams in + const chunk = event.delta.partial_json; + toolInput += chunk; + console.log(` Input chunk: ${chunk}`); + } + } else if (event.type === "content_block_stop") { + // Tool call complete - show final input + if (currentTool) { + console.log(`Tool ${currentTool} called with: ${toolInput}`); + currentTool = null; + } + } + } + } + ``` + + +## Build a streaming UI + +This example combines text and tool streaming into a cohesive UI. It tracks whether the agent is currently executing a tool (using an `in_tool` flag) to show status indicators like `[Using Read...]` while tools run. Text streams normally when not in a tool, and tool completion triggers a "done" message. This pattern is useful for chat interfaces that need to show progress during multi-step agent tasks. + + + ```python Python theme={null} + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + from claude_agent_sdk.types import StreamEvent + import asyncio + import sys + + + async def streaming_ui(): + options = ClaudeAgentOptions( + include_partial_messages=True, + allowed_tools=["Read", "Bash", "Grep"], + ) + + # Track whether we're currently in a tool call + in_tool = False + + async for message in query( + prompt="Find all TODO comments in the codebase", options=options + ): + if isinstance(message, StreamEvent): + event = message.event + event_type = event.get("type") + + if event_type == "content_block_start": + content_block = event.get("content_block", {}) + if content_block.get("type") == "tool_use": + # Tool call is starting - show status indicator + tool_name = content_block.get("name") + print(f"\n[Using {tool_name}...]", end="", flush=True) + in_tool = True + + elif event_type == "content_block_delta": + delta = event.get("delta", {}) + # Only stream text when not executing a tool + if delta.get("type") == "text_delta" and not in_tool: + sys.stdout.write(delta.get("text", "")) + sys.stdout.flush() + + elif event_type == "content_block_stop": + if in_tool: + # Tool call finished + print(" done", flush=True) + in_tool = False + + elif isinstance(message, ResultMessage): + # Agent finished all work + print(f"\n\n--- Complete ---") + + + asyncio.run(streaming_ui()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Track whether we're currently in a tool call + let inTool = false; + + for await (const message of query({ + prompt: "Find all TODO comments in the codebase", + options: { + includePartialMessages: true, + allowedTools: ["Read", "Bash", "Grep"] + } + })) { + if (message.type === "stream_event") { + const event = message.event; + + if (event.type === "content_block_start") { + if (event.content_block.type === "tool_use") { + // Tool call is starting - show status indicator + process.stdout.write(`\n[Using ${event.content_block.name}...]`); + inTool = true; + } + } else if (event.type === "content_block_delta") { + // Only stream text when not executing a tool + if (event.delta.type === "text_delta" && !inTool) { + process.stdout.write(event.delta.text); + } + } else if (event.type === "content_block_stop") { + if (inTool) { + // Tool call finished + console.log(" done"); + inTool = false; + } + } + } else if (message.type === "result") { + // Agent finished all work + console.log("\n\n--- Complete ---"); + } + } + ``` + + +## Known limitations + +Some SDK features are incompatible with streaming: + +* **Extended thinking**: when you explicitly set `max_thinking_tokens` (Python) or `maxThinkingTokens` (TypeScript), `StreamEvent` messages are not emitted. You'll only receive complete messages after each turn. Note that thinking is disabled by default in the SDK, so streaming works unless you enable it. +* **Structured output**: the JSON result appears only in the final `ResultMessage.structured_output`, not as streaming deltas. See [structured outputs](/en/agent-sdk/structured-outputs) for details. + +## Next steps + +Now that you can stream text and tool calls in real-time, explore these related topics: + +* [Interactive vs one-shot queries](/en/agent-sdk/streaming-vs-single-mode): choose between input modes for your use case +* [Structured outputs](/en/agent-sdk/structured-outputs): get typed JSON responses from the agent +* [Permissions](/en/agent-sdk/permissions): control which tools the agent can use diff --git a/content/en/docs/claude-code/agent-sdk/streaming-vs-single-mode.md b/content/en/docs/claude-code/agent-sdk/streaming-vs-single-mode.md new file mode 100644 index 000000000..3f577ac8b --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/streaming-vs-single-mode.md @@ -0,0 +1,295 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Streaming Input + +> Understanding the two input modes for Claude Agent SDK and when to use each + +## Overview + +The Claude Agent SDK supports two distinct input modes for interacting with agents: + +* **Streaming Input Mode** (Default & Recommended) - A persistent, interactive session +* **Single Message Input** - One-shot queries that use session state and resuming + +This guide explains the differences, benefits, and use cases for each mode to help you choose the right approach for your application. + +## Streaming Input Mode (Recommended) + +Streaming input mode is the **preferred** way to use the Claude Agent SDK. It provides full access to the agent's capabilities and enables rich, interactive experiences. + +It allows the agent to operate as a long lived process that takes in user input, handles interruptions, surfaces permission requests, and handles session management. + +### How It Works + +```mermaid theme={null} +sequenceDiagram + participant App as Your Application + participant Agent as Claude Agent + participant Tools as Tools/Hooks + participant FS as Environment/
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    File System + + App->>Agent: Initialize with AsyncGenerator + activate Agent + + App->>Agent: Yield Message 1 + Agent->>Tools: Execute tools + Tools->>FS: Read files + FS-->>Tools: File contents + Tools->>FS: Write/Edit files + FS-->>Tools: Success/Error + Agent-->>App: Stream partial response + Agent-->>App: Stream more content... + Agent->>App: Complete Message 1 + + App->>Agent: Yield Message 2 + Image + Agent->>Tools: Process image & execute + Tools->>FS: Access filesystem + FS-->>Tools: Operation results + Agent-->>App: Stream response 2 + + App->>Agent: Queue Message 3 + App->>Agent: Interrupt/Cancel + Agent->>App: Handle interruption + + Note over App,Agent: Session stays alive + Note over Tools,FS: Persistent file system
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    state maintained + + deactivate Agent +``` + +### Benefits + + + + Attach images directly to messages for visual analysis and understanding + + + + Send multiple messages that process sequentially, with ability to interrupt + + + + Full access to all tools and custom MCP servers during the session + + + + Use lifecycle hooks to customize behavior at various points + + + + See responses as they're generated, not just final results + + + + Maintain conversation context across multiple turns naturally + + + +### Implementation Example + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + import { readFile } from "fs/promises"; + + async function* generateMessages() { + // First message + yield { + type: "user" as const, + message: { + role: "user" as const, + content: "Analyze this codebase for security issues" + } + }; + + // Wait for conditions or user input + await new Promise((resolve) => setTimeout(resolve, 2000)); + + // Follow-up with image + yield { + type: "user" as const, + message: { + role: "user" as const, + content: [ + { + type: "text", + text: "Review this architecture diagram" + }, + { + type: "image", + source: { + type: "base64", + media_type: "image/png", + data: await readFile("diagram.png", "base64") + } + } + ] + } + }; + } + + // Process streaming responses + for await (const message of query({ + prompt: generateMessages(), + options: { + maxTurns: 10, + allowedTools: ["Read", "Grep"] + } + })) { + if (message.type === "result") { + console.log(message.result); + } + } + ``` + + ```python Python theme={null} + from claude_agent_sdk import ( + ClaudeSDKClient, + ClaudeAgentOptions, + AssistantMessage, + TextBlock, + ) + import asyncio + import base64 + + + async def streaming_analysis(): + async def message_generator(): + # First message + yield { + "type": "user", + "message": { + "role": "user", + "content": "Analyze this codebase for security issues", + }, + } + + # Wait for conditions + await asyncio.sleep(2) + + # Follow-up with image + with open("diagram.png", "rb") as f: + image_data = base64.b64encode(f.read()).decode() + + yield { + "type": "user", + "message": { + "role": "user", + "content": [ + {"type": "text", "text": "Review this architecture diagram"}, + { + "type": "image", + "source": { + "type": "base64", + "media_type": "image/png", + "data": image_data, + }, + }, + ], + }, + } + + # Use ClaudeSDKClient for streaming input + options = ClaudeAgentOptions(max_turns=10, allowed_tools=["Read", "Grep"]) + + async with ClaudeSDKClient(options) as client: + # Send streaming input + await client.query(message_generator()) + + # Process responses + async for message in client.receive_response(): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(block.text) + + + asyncio.run(streaming_analysis()) + ``` + + +## Single Message Input + +Single message input is simpler but more limited. + +### When to Use Single Message Input + +Use single message input when: + +* You need a one-shot response +* You do not need image attachments, hooks, etc. +* You need to operate in a stateless environment, such as a lambda function + +### Limitations + + + Single message input mode does **not** support: + + * Direct image attachments in messages + * Dynamic message queueing + * Real-time interruption + * Hook integration + * Natural multi-turn conversations + + +### Implementation Example + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Simple one-shot query + for await (const message of query({ + prompt: "Explain the authentication flow", + options: { + maxTurns: 1, + allowedTools: ["Read", "Grep"] + } + })) { + if (message.type === "result") { + console.log(message.result); + } + } + + // Continue conversation with session management + for await (const message of query({ + prompt: "Now explain the authorization process", + options: { + continue: true, + maxTurns: 1 + } + })) { + if (message.type === "result") { + console.log(message.result); + } + } + ``` + + ```python Python theme={null} + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + import asyncio + + + async def single_message_example(): + # Simple one-shot query using query() function + async for message in query( + prompt="Explain the authentication flow", + options=ClaudeAgentOptions(max_turns=1, allowed_tools=["Read", "Grep"]), + ): + if isinstance(message, ResultMessage): + print(message.result) + + # Continue conversation with session management + async for message in query( + prompt="Now explain the authorization process", + options=ClaudeAgentOptions(continue_conversation=True, max_turns=1), + ): + if isinstance(message, ResultMessage): + print(message.result) + + + asyncio.run(single_message_example()) + ``` + diff --git a/content/en/docs/claude-code/agent-sdk/structured-outputs.md b/content/en/docs/claude-code/agent-sdk/structured-outputs.md new file mode 100644 index 000000000..bcae39249 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/structured-outputs.md @@ -0,0 +1,410 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Get structured output from agents + +> Return validated JSON from agent workflows using JSON Schema, Zod, or Pydantic. Get type-safe, structured data after multi-turn tool use. + +Structured outputs let you define the exact shape of data you want back from an agent. The agent can use any tools it needs to complete the task, and you still get validated JSON matching your schema at the end. Define a [JSON Schema](https://json-schema.org/understanding-json-schema/about) for the structure you need, and the SDK guarantees the output matches it. + +For full type safety, use [Zod](#type-safe-schemas-with-zod-and-pydantic) (TypeScript) or [Pydantic](#type-safe-schemas-with-zod-and-pydantic) (Python) to define your schema and get strongly-typed objects back. + +## Why structured outputs? + +Agents return free-form text by default, which works for chat but not when you need to use the output programmatically. Structured outputs give you typed data you can pass directly to your application logic, database, or UI components. + +Consider a recipe app where an agent searches the web and brings back recipes. Without structured outputs, you get free-form text that you'd need to parse yourself. With structured outputs, you define the shape you want and get typed data you can use directly in your app. + + + + ```text theme={null} + Here's a classic chocolate chip cookie recipe! + + **Chocolate Chip Cookies** + Prep time: 15 minutes | Cook time: 10 minutes + + Ingredients: + - 2 1/4 cups all-purpose flour + - 1 cup butter, softened + ... + ``` + + To use this in your app, you'd need to parse out the title, convert "15 minutes" to a number, separate ingredients from instructions, and handle inconsistent formatting across responses. + + + + ```json theme={null} + { + "name": "Chocolate Chip Cookies", + "prep_time_minutes": 15, + "cook_time_minutes": 10, + "ingredients": [ + { "item": "all-purpose flour", "amount": 2.25, "unit": "cups" }, + { "item": "butter, softened", "amount": 1, "unit": "cup" } + // ... + ], + "steps": ["Preheat oven to 375°F", "Cream butter and sugar" /* ... */] + } + ``` + + Typed data you can use directly in your UI. + + + +## Quick start + +To use structured outputs, define a [JSON Schema](https://json-schema.org/understanding-json-schema/about) describing the shape of data you want, then pass it to `query()` via the `outputFormat` option (TypeScript) or `output_format` option (Python). When the agent finishes, the result message includes a `structured_output` field with validated data matching your schema. + +The example below asks the agent to research Anthropic and return the company name, year founded, and headquarters as structured output. + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Define the shape of data you want back + const schema = { + type: "object", + properties: { + company_name: { type: "string" }, + founded_year: { type: "number" }, + headquarters: { type: "string" } + }, + required: ["company_name"] + }; + + for await (const message of query({ + prompt: "Research Anthropic and provide key company information", + options: { + outputFormat: { + type: "json_schema", + schema: schema + } + } + })) { + // The result message contains structured_output with validated data + if (message.type === "result" && message.subtype === "success" && message.structured_output) { + console.log(message.structured_output); + // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" } + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + # Define the shape of data you want back + schema = { + "type": "object", + "properties": { + "company_name": {"type": "string"}, + "founded_year": {"type": "number"}, + "headquarters": {"type": "string"}, + }, + "required": ["company_name"], + } + + + async def main(): + async for message in query( + prompt="Research Anthropic and provide key company information", + options=ClaudeAgentOptions( + output_format={"type": "json_schema", "schema": schema} + ), + ): + # The result message contains structured_output with validated data + if isinstance(message, ResultMessage) and message.structured_output: + print(message.structured_output) + # {'company_name': 'Anthropic', 'founded_year': 2021, 'headquarters': 'San Francisco, CA'} + + + asyncio.run(main()) + ``` + + +## Type-safe schemas with Zod and Pydantic + +Instead of writing JSON Schema by hand, you can use [Zod](https://zod.dev/) (TypeScript) or [Pydantic](https://docs.pydantic.dev/latest/) (Python) to define your schema. These libraries generate the JSON Schema for you and let you parse the response into a fully-typed object you can use throughout your codebase with autocomplete and type checking. + +The example below defines a schema for a feature implementation plan with a summary, list of steps (each with complexity level), and potential risks. The agent plans the feature and returns a typed `FeaturePlan` object. You can then access properties like `plan.summary` and iterate over `plan.steps` with full type safety. + + + ```typescript TypeScript theme={null} + import { z } from "zod"; + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Define schema with Zod + const FeaturePlan = z.object({ + feature_name: z.string(), + summary: z.string(), + steps: z.array( + z.object({ + step_number: z.number(), + description: z.string(), + estimated_complexity: z.enum(["low", "medium", "high"]) + }) + ), + risks: z.array(z.string()) + }); + + type FeaturePlan = z.infer; + + // Convert to JSON Schema + const schema = z.toJSONSchema(FeaturePlan); + + // Use in query + for await (const message of query({ + prompt: + "Plan how to add dark mode support to a React app. Break it into implementation steps.", + options: { + outputFormat: { + type: "json_schema", + schema: schema + } + } + })) { + if (message.type === "result" && message.subtype === "success" && message.structured_output) { + // Validate and get fully typed result + const parsed = FeaturePlan.safeParse(message.structured_output); + if (parsed.success) { + const plan: FeaturePlan = parsed.data; + console.log(`Feature: ${plan.feature_name}`); + console.log(`Summary: ${plan.summary}`); + plan.steps.forEach((step) => { + console.log(`${step.step_number}. [${step.estimated_complexity}] ${step.description}`); + }); + } + } + } + ``` + + ```python Python theme={null} + import asyncio + from pydantic import BaseModel + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + + class Step(BaseModel): + step_number: int + description: str + estimated_complexity: str # 'low', 'medium', 'high' + + + class FeaturePlan(BaseModel): + feature_name: str + summary: str + steps: list[Step] + risks: list[str] + + + async def main(): + async for message in query( + prompt="Plan how to add dark mode support to a React app. Break it into implementation steps.", + options=ClaudeAgentOptions( + output_format={ + "type": "json_schema", + "schema": FeaturePlan.model_json_schema(), + } + ), + ): + if isinstance(message, ResultMessage) and message.structured_output: + # Validate and get fully typed result + plan = FeaturePlan.model_validate(message.structured_output) + print(f"Feature: {plan.feature_name}") + print(f"Summary: {plan.summary}") + for step in plan.steps: + print( + f"{step.step_number}. [{step.estimated_complexity}] {step.description}" + ) + + + asyncio.run(main()) + ``` + + +**Benefits:** + +* Full type inference (TypeScript) and type hints (Python) +* Runtime validation with `safeParse()` or `model_validate()` +* Better error messages +* Composable, reusable schemas + +## Output format configuration + +The `outputFormat` (TypeScript) or `output_format` (Python) option accepts an object with: + +* `type`: Set to `"json_schema"` for structured outputs +* `schema`: A [JSON Schema](https://json-schema.org/understanding-json-schema/about) object defining your output structure. You can generate this from a Zod schema with `z.toJSONSchema()` or a Pydantic model with `.model_json_schema()` + +The SDK supports standard JSON Schema features including all basic types (object, array, string, number, boolean, null), `enum`, `const`, `required`, nested objects, and `$ref` definitions. For the full list of supported features and limitations, see [JSON Schema limitations](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#json-schema-limitations). + +## Example: TODO tracking agent + +This example demonstrates how structured outputs work with multi-step tool use. The agent needs to find TODO comments in the codebase, then look up git blame information for each one. It autonomously decides which tools to use (Grep to search, Bash to run git commands) and combines the results into a single structured response. + +The schema includes optional fields (`author` and `date`) since git blame information might not be available for all files. The agent fills in what it can find and omits the rest. + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Define structure for TODO extraction + const todoSchema = { + type: "object", + properties: { + todos: { + type: "array", + items: { + type: "object", + properties: { + text: { type: "string" }, + file: { type: "string" }, + line: { type: "number" }, + author: { type: "string" }, + date: { type: "string" } + }, + required: ["text", "file", "line"] + } + }, + total_count: { type: "number" } + }, + required: ["todos", "total_count"] + }; + + // Agent uses Grep to find TODOs, Bash to get git blame info + for await (const message of query({ + prompt: "Find all TODO comments in this codebase and identify who added them", + options: { + outputFormat: { + type: "json_schema", + schema: todoSchema + } + } + })) { + if (message.type === "result" && message.subtype === "success" && message.structured_output) { + const data = message.structured_output as { total_count: number; todos: Array<{ file: string; line: number; text: string; author?: string; date?: string }> }; + console.log(`Found ${data.total_count} TODOs`); + data.todos.forEach((todo) => { + console.log(`${todo.file}:${todo.line} - ${todo.text}`); + if (todo.author) { + console.log(` Added by ${todo.author} on ${todo.date}`); + } + }); + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + # Define structure for TODO extraction + todo_schema = { + "type": "object", + "properties": { + "todos": { + "type": "array", + "items": { + "type": "object", + "properties": { + "text": {"type": "string"}, + "file": {"type": "string"}, + "line": {"type": "number"}, + "author": {"type": "string"}, + "date": {"type": "string"}, + }, + "required": ["text", "file", "line"], + }, + }, + "total_count": {"type": "number"}, + }, + "required": ["todos", "total_count"], + } + + + async def main(): + # Agent uses Grep to find TODOs, Bash to get git blame info + async for message in query( + prompt="Find all TODO comments in this codebase and identify who added them", + options=ClaudeAgentOptions( + output_format={"type": "json_schema", "schema": todo_schema} + ), + ): + if isinstance(message, ResultMessage) and message.structured_output: + data = message.structured_output + print(f"Found {data['total_count']} TODOs") + for todo in data["todos"]: + print(f"{todo['file']}:{todo['line']} - {todo['text']}") + if "author" in todo: + print(f" Added by {todo['author']} on {todo['date']}") + + + asyncio.run(main()) + ``` + + +## Error handling + +Structured output generation can fail when the agent cannot produce valid JSON matching your schema. This typically happens when the schema is too complex for the task, the task itself is ambiguous, or the agent hits its retry limit trying to fix validation errors. + +When an error occurs, the result message has a `subtype` indicating what went wrong: + +| Subtype | Meaning | +| ------------------------------------- | ----------------------------------------------------------- | +| `success` | Output was generated and validated successfully | +| `error_max_structured_output_retries` | Agent couldn't produce valid output after multiple attempts | + +The example below checks the `subtype` field to determine whether the output was generated successfully or if you need to handle a failure: + + + ```typescript TypeScript theme={null} + for await (const msg of query({ + prompt: "Extract contact info from the document", + options: { + outputFormat: { + type: "json_schema", + schema: contactSchema + } + } + })) { + if (msg.type === "result") { + if (msg.subtype === "success" && msg.structured_output) { + // Use the validated output + console.log(msg.structured_output); + } else if (msg.subtype === "error_max_structured_output_retries") { + // Handle the failure - retry with simpler prompt, fall back to unstructured, etc. + console.error("Could not produce valid output"); + } + } + } + ``` + + ```python Python theme={null} + async for message in query( + prompt="Extract contact info from the document", + options=ClaudeAgentOptions( + output_format={"type": "json_schema", "schema": contact_schema} + ), + ): + if isinstance(message, ResultMessage): + if message.subtype == "success" and message.structured_output: + # Use the validated output + print(message.structured_output) + elif message.subtype == "error_max_structured_output_retries": + # Handle the failure + print("Could not produce valid output") + ``` + + +**Tips for avoiding errors:** + +* **Keep schemas focused.** Deeply nested schemas with many required fields are harder to satisfy. Start simple and add complexity as needed. +* **Match schema to task.** If the task might not have all the information your schema requires, make those fields optional. +* **Use clear prompts.** Ambiguous prompts make it harder for the agent to know what output to produce. + +## Related resources + +* [JSON Schema documentation](https://json-schema.org/): learn JSON Schema syntax for defining complex schemas with nested objects, arrays, enums, and validation constraints +* [API Structured Outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs): use structured outputs with the Claude API directly for single-turn requests without tool use +* [Custom tools](/en/agent-sdk/custom-tools): give your agent custom tools to call during execution before returning structured output diff --git a/content/en/docs/claude-code/agent-sdk/subagents.md b/content/en/docs/claude-code/agent-sdk/subagents.md new file mode 100644 index 000000000..b4d7dd8dc --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/subagents.md @@ -0,0 +1,594 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Subagents in the SDK + +> Define and invoke subagents to isolate context, run tasks in parallel, and apply specialized instructions in your Claude Agent SDK applications. + +Subagents are separate agent instances that your main agent can spawn to handle focused subtasks. +Use subagents to isolate context for focused subtasks, run multiple analyses in parallel, and apply specialized instructions without bloating the main agent's prompt. + +This guide explains how to define and use subagents in the SDK using the `agents` parameter. + +## Overview + +You can create subagents in three ways: + +* **Programmatically**: use the `agents` parameter in your `query()` options ([TypeScript](/en/agent-sdk/typescript#agent-definition), [Python](/en/agent-sdk/python#agent-definition)) +* **Filesystem-based**: define agents as markdown files in `.claude/agents/` directories (see [defining subagents as files](/en/sub-agents)) +* **Built-in general-purpose**: Claude can invoke the built-in `general-purpose` subagent at any time via the Agent tool without you defining anything + +This guide focuses on the programmatic approach, which is recommended for SDK applications. + +When you define subagents, Claude determines whether to invoke them based on each subagent's `description` field. Write clear descriptions that explain when the subagent should be used, and Claude will automatically delegate appropriate tasks. You can also explicitly request a subagent by name in your prompt (for example, "Use the code-reviewer agent to..."). + +## Benefits of using subagents + +### Context isolation + +Each subagent runs in its own fresh conversation. Intermediate tool calls and results stay inside the subagent; only its final message returns to the parent. See [What subagents inherit](#what-subagents-inherit) for exactly what's in the subagent's context. + +**Example:** a `research-assistant` subagent can explore dozens of files without any of that content accumulating in the main conversation. The parent receives a concise summary, not every file the subagent read. + +### Parallelization + +Multiple subagents can run concurrently, dramatically speeding up complex workflows. + +**Example:** during a code review, you can run `style-checker`, `security-scanner`, and `test-coverage` subagents simultaneously, reducing review time from minutes to seconds. + +### Specialized instructions and knowledge + +Each subagent can have tailored system prompts with specific expertise, best practices, and constraints. + +**Example:** a `database-migration` subagent can have detailed knowledge about SQL best practices, rollback strategies, and data integrity checks that would be unnecessary noise in the main agent's instructions. + +### Tool restrictions + +Subagents can be limited to specific tools, reducing the risk of unintended actions. + +**Example:** a `doc-reviewer` subagent might only have access to Read and Grep tools, ensuring it can analyze but never accidentally modify your documentation files. + +## Creating subagents + +### Programmatic definition (recommended) + +Define subagents directly in your code using the `agents` parameter. This example creates two subagents: a code reviewer with read-only access and a test runner that can execute commands. The `Agent` tool must be included in `allowedTools` since Claude invokes subagents through the Agent tool. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition + + + async def main(): + async for message in query( + prompt="Review the authentication module for security issues", + options=ClaudeAgentOptions( + # Agent tool is required for subagent invocation + allowed_tools=["Read", "Grep", "Glob", "Agent"], + agents={ + "code-reviewer": AgentDefinition( + # description tells Claude when to use this subagent + description="Expert code review specialist. Use for quality, security, and maintainability reviews.", + # prompt defines the subagent's behavior and expertise + prompt="""You are a code review specialist with expertise in security, performance, and best practices. + + When reviewing code: + - Identify security vulnerabilities + - Check for performance issues + - Verify adherence to coding standards + - Suggest specific improvements + + Be thorough but concise in your feedback.""", + # tools restricts what the subagent can do (read-only here) + tools=["Read", "Grep", "Glob"], + # model overrides the default model for this subagent + model="sonnet", + ), + "test-runner": AgentDefinition( + description="Runs and analyzes test suites. Use for test execution and coverage analysis.", + prompt="""You are a test execution specialist. Run tests and provide clear analysis of results. + + Focus on: + - Running test commands + - Analyzing test output + - Identifying failing tests + - Suggesting fixes for failures""", + # Bash access lets this subagent run test commands + tools=["Bash", "Read", "Grep"], + ), + }, + ), + ): + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Review the authentication module for security issues", + options: { + // Agent tool is required for subagent invocation + allowedTools: ["Read", "Grep", "Glob", "Agent"], + agents: { + "code-reviewer": { + // description tells Claude when to use this subagent + description: + "Expert code review specialist. Use for quality, security, and maintainability reviews.", + // prompt defines the subagent's behavior and expertise + prompt: `You are a code review specialist with expertise in security, performance, and best practices. + + When reviewing code: + - Identify security vulnerabilities + - Check for performance issues + - Verify adherence to coding standards + - Suggest specific improvements + + Be thorough but concise in your feedback.`, + // tools restricts what the subagent can do (read-only here) + tools: ["Read", "Grep", "Glob"], + // model overrides the default model for this subagent + model: "sonnet" + }, + "test-runner": { + description: + "Runs and analyzes test suites. Use for test execution and coverage analysis.", + prompt: `You are a test execution specialist. Run tests and provide clear analysis of results. + + Focus on: + - Running test commands + - Analyzing test output + - Identifying failing tests + - Suggesting fixes for failures`, + // Bash access lets this subagent run test commands + tools: ["Bash", "Read", "Grep"] + } + } + } + })) { + if ("result" in message) console.log(message.result); + } + ``` + + +### AgentDefinition configuration + +| Field | Type | Required | Description | +| :------------ | :------------------------------------------- | :------- | :--------------------------------------------------------------- | +| `description` | `string` | Yes | Natural language description of when to use this agent | +| `prompt` | `string` | Yes | The agent's system prompt defining its role and behavior | +| `tools` | `string[]` | No | Array of allowed tool names. If omitted, inherits all tools | +| `model` | `'sonnet' \| 'opus' \| 'haiku' \| 'inherit'` | No | Model override for this agent. Defaults to main model if omitted | +| `skills` | `string[]` | No | List of skill names available to this agent | +| `memory` | `'user' \| 'project' \| 'local'` | No | Memory source for this agent (Python only) | +| `mcpServers` | `(string \| object)[]` | No | MCP servers available to this agent, by name or inline config | + + + Subagents cannot spawn their own subagents. Don't include `Agent` in a subagent's `tools` array. + + +### Filesystem-based definition (alternative) + +You can also define subagents as markdown files in `.claude/agents/` directories. See the [Claude Code subagents documentation](/en/sub-agents) for details on this approach. Programmatically defined agents take precedence over filesystem-based agents with the same name. + + + Even without defining custom subagents, Claude can spawn the built-in `general-purpose` subagent when `Agent` is in your `allowedTools`. This is useful for delegating research or exploration tasks without creating specialized agents. + + +## What subagents inherit + +A subagent's context window starts fresh (no parent conversation) but isn't empty. The only channel from parent to subagent is the Agent tool's prompt string, so include any file paths, error messages, or decisions the subagent needs directly in that prompt. + +| The subagent receives | The subagent does not receive | +| :--------------------------------------------------------------------------- | :------------------------------------------------- | +| Its own system prompt (`AgentDefinition.prompt`) and the Agent tool's prompt | The parent's conversation history or tool results | +| Project CLAUDE.md (loaded via `settingSources`) | Skills (unless listed in `AgentDefinition.skills`) | +| Tool definitions (inherited from parent, or the subset in `tools`) | The parent's system prompt | + + + The parent receives the subagent's final message verbatim as the Agent tool result, but may summarize it in its own response. To preserve subagent output verbatim in the user-facing response, include an instruction to do so in the prompt or `systemPrompt` option you pass to the **main** `query()` call. + + +## Invoking subagents + +### Automatic invocation + +Claude automatically decides when to invoke subagents based on the task and each subagent's `description`. For example, if you define a `performance-optimizer` subagent with the description "Performance optimization specialist for query tuning", Claude will invoke it when your prompt mentions optimizing queries. + +Write clear, specific descriptions so Claude can match tasks to the right subagent. + +### Explicit invocation + +To guarantee Claude uses a specific subagent, mention it by name in your prompt: + +```text theme={null} +"Use the code-reviewer agent to check the authentication module" +``` + +This bypasses automatic matching and directly invokes the named subagent. + +### Dynamic agent configuration + +You can create agent definitions dynamically based on runtime conditions. This example creates a security reviewer with different strictness levels, using a more powerful model for strict reviews. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition + + + # Factory function that returns an AgentDefinition + # This pattern lets you customize agents based on runtime conditions + def create_security_agent(security_level: str) -> AgentDefinition: + is_strict = security_level == "strict" + return AgentDefinition( + description="Security code reviewer", + # Customize the prompt based on strictness level + prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...", + tools=["Read", "Grep", "Glob"], + # Key insight: use a more capable model for high-stakes reviews + model="opus" if is_strict else "sonnet", + ) + + + async def main(): + # The agent is created at query time, so each request can use different settings + async for message in query( + prompt="Review this PR for security issues", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Grep", "Glob", "Agent"], + agents={ + # Call the factory with your desired configuration + "security-reviewer": create_security_agent("strict") + }, + ), + ): + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query, type AgentDefinition } from "@anthropic-ai/claude-agent-sdk"; + + // Factory function that returns an AgentDefinition + // This pattern lets you customize agents based on runtime conditions + function createSecurityAgent(securityLevel: "basic" | "strict"): AgentDefinition { + const isStrict = securityLevel === "strict"; + return { + description: "Security code reviewer", + // Customize the prompt based on strictness level + prompt: `You are a ${isStrict ? "strict" : "balanced"} security reviewer...`, + tools: ["Read", "Grep", "Glob"], + // Key insight: use a more capable model for high-stakes reviews + model: isStrict ? "opus" : "sonnet" + }; + } + + // The agent is created at query time, so each request can use different settings + for await (const message of query({ + prompt: "Review this PR for security issues", + options: { + allowedTools: ["Read", "Grep", "Glob", "Agent"], + agents: { + // Call the factory with your desired configuration + "security-reviewer": createSecurityAgent("strict") + } + } + })) { + if ("result" in message) console.log(message.result); + } + ``` + + +## Detecting subagent invocation + +Subagents are invoked via the Agent tool. To detect when a subagent is invoked, check for `tool_use` blocks where `name` is `"Agent"`. Messages from within a subagent's context include a `parent_tool_use_id` field. + + + The tool name was renamed from `"Task"` to `"Agent"` in Claude Code v2.1.63. Current SDK releases emit `"Agent"` in `tool_use` blocks but still use `"Task"` in the `system:init` tools list and in `result.permission_denials[].tool_name`. Checking both values in `block.name` ensures compatibility across SDK versions. + + +This example iterates through streamed messages, logging when a subagent is invoked and when subsequent messages originate from within that subagent's execution context. + + + The message structure differs between SDKs. In Python, content blocks are accessed directly via `message.content`. In TypeScript, `SDKAssistantMessage` wraps the Claude API message, so content is accessed via `message.message.content`. + + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition + + + async def main(): + async for message in query( + prompt="Use the code-reviewer agent to review this codebase", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Glob", "Grep", "Agent"], + agents={ + "code-reviewer": AgentDefinition( + description="Expert code reviewer.", + prompt="Analyze code quality and suggest improvements.", + tools=["Read", "Glob", "Grep"], + ) + }, + ), + ): + # Check for subagent invocation. Match both names: older SDK + # versions emitted "Task", current versions emit "Agent". + if hasattr(message, "content") and message.content: + for block in message.content: + if getattr(block, "type", None) == "tool_use" and block.name in ( + "Task", + "Agent", + ): + print(f"Subagent invoked: {block.input.get('subagent_type')}") + + # Check if this message is from within a subagent's context + if hasattr(message, "parent_tool_use_id") and message.parent_tool_use_id: + print(" (running inside subagent)") + + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Use the code-reviewer agent to review this codebase", + options: { + allowedTools: ["Read", "Glob", "Grep", "Agent"], + agents: { + "code-reviewer": { + description: "Expert code reviewer.", + prompt: "Analyze code quality and suggest improvements.", + tools: ["Read", "Glob", "Grep"] + } + } + } + })) { + const msg = message as any; + + // Check for subagent invocation. Match both names: older SDK versions + // emitted "Task", current versions emit "Agent". + for (const block of msg.message?.content ?? []) { + if (block.type === "tool_use" && (block.name === "Task" || block.name === "Agent")) { + console.log(`Subagent invoked: ${block.input.subagent_type}`); + } + } + + // Check if this message is from within a subagent's context + if (msg.parent_tool_use_id) { + console.log(" (running inside subagent)"); + } + + if ("result" in message) { + console.log(message.result); + } + } + ``` + + +## Resuming subagents + +Subagents can be resumed to continue where they left off. Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh. + +When a subagent completes, Claude receives its agent ID in the Agent tool result. To resume a subagent programmatically: + +1. **Capture the session ID**: Extract `session_id` from messages during the first query +2. **Extract the agent ID**: Parse `agentId` from the message content +3. **Resume the session**: Pass `resume: sessionId` in the second query's options, and include the agent ID in your prompt + + + You must resume the same session to access the subagent's transcript. Each `query()` call starts a new session by default, so pass `resume: sessionId` to continue in the same session. + + If you're using a custom agent (not a built-in one), you also need to pass the same agent definition in the `agents` parameter for both queries. + + +The example below demonstrates this flow: the first query runs a subagent and captures the session ID and agent ID, then the second query resumes the session to ask a follow-up question that requires context from the first analysis. + + + ```typescript TypeScript theme={null} + import { query, type SDKMessage } from "@anthropic-ai/claude-agent-sdk"; + + // Helper to extract agentId from message content + // Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.) + function extractAgentId(message: SDKMessage): string | undefined { + if (!("message" in message)) return undefined; + // Stringify the content so we can search it without traversing nested blocks + const content = JSON.stringify(message.message.content); + const match = content.match(/agentId:\s*([a-f0-9-]+)/); + return match?.[1]; + } + + let agentId: string | undefined; + let sessionId: string | undefined; + + // First invocation - use the Explore agent to find API endpoints + for await (const message of query({ + prompt: "Use the Explore agent to find all API endpoints in this codebase", + options: { allowedTools: ["Read", "Grep", "Glob", "Agent"] } + })) { + // Capture session_id from ResultMessage (needed to resume this session) + if ("session_id" in message) sessionId = message.session_id; + // Search message content for the agentId (appears in Agent tool results) + const extractedId = extractAgentId(message); + if (extractedId) agentId = extractedId; + // Print the final result + if ("result" in message) console.log(message.result); + } + + // Second invocation - resume and ask follow-up + if (agentId && sessionId) { + for await (const message of query({ + prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`, + options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], resume: sessionId } + })) { + if ("result" in message) console.log(message.result); + } + } + ``` + + ```python Python theme={null} + import asyncio + import json + import re + from claude_agent_sdk import query, ClaudeAgentOptions + + + def extract_agent_id(text: str) -> str | None: + """Extract agentId from Agent tool result text.""" + match = re.search(r"agentId:\s*([a-f0-9-]+)", text) + return match.group(1) if match else None + + + async def main(): + agent_id = None + session_id = None + + # First invocation - use the Explore agent to find API endpoints + async for message in query( + prompt="Use the Explore agent to find all API endpoints in this codebase", + options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"]), + ): + # Capture session_id from ResultMessage (needed to resume this session) + if hasattr(message, "session_id"): + session_id = message.session_id + # Search message content for the agentId (appears in Agent tool results) + if hasattr(message, "content"): + # Stringify the content so we can search it without traversing nested blocks + content_str = json.dumps(message.content, default=str) + extracted = extract_agent_id(content_str) + if extracted: + agent_id = extracted + # Print the final result + if hasattr(message, "result"): + print(message.result) + + # Second invocation - resume and ask follow-up + if agent_id and session_id: + async for message in query( + prompt=f"Resume agent {agent_id} and list the top 3 most complex endpoints", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Grep", "Glob", "Agent"], resume=session_id + ), + ): + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + +Subagent transcripts persist independently of the main conversation: + +* **Main conversation compaction**: When the main conversation compacts, subagent transcripts are unaffected. They're stored in separate files. +* **Session persistence**: Subagent transcripts persist within their session. You can resume a subagent after restarting Claude Code by resuming the same session. +* **Automatic cleanup**: Transcripts are cleaned up based on the `cleanupPeriodDays` setting (default: 30 days). + +## Tool restrictions + +Subagents can have restricted tool access via the `tools` field: + +* **Omit the field**: agent inherits all available tools (default) +* **Specify tools**: agent can only use listed tools + +This example creates a read-only analysis agent that can examine code but cannot modify files or run commands. + + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition + + + async def main(): + async for message in query( + prompt="Analyze the architecture of this codebase", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Grep", "Glob", "Agent"], + agents={ + "code-analyzer": AgentDefinition( + description="Static code analysis and architecture review", + prompt="""You are a code architecture analyst. Analyze code structure, + identify patterns, and suggest improvements without making changes.""", + # Read-only tools: no Edit, Write, or Bash access + tools=["Read", "Grep", "Glob"], + ) + }, + ), + ): + if hasattr(message, "result"): + print(message.result) + + + asyncio.run(main()) + ``` + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Analyze the architecture of this codebase", + options: { + allowedTools: ["Read", "Grep", "Glob", "Agent"], + agents: { + "code-analyzer": { + description: "Static code analysis and architecture review", + prompt: `You are a code architecture analyst. Analyze code structure, + identify patterns, and suggest improvements without making changes.`, + // Read-only tools: no Edit, Write, or Bash access + tools: ["Read", "Grep", "Glob"] + } + } + } + })) { + if ("result" in message) console.log(message.result); + } + ``` + + +### Common tool combinations + +| Use case | Tools | Description | +| :----------------- | :-------------------------------------- | :-------------------------------------------------- | +| Read-only analysis | `Read`, `Grep`, `Glob` | Can examine code but not modify or execute | +| Test execution | `Bash`, `Read`, `Grep` | Can run commands and analyze output | +| Code modification | `Read`, `Edit`, `Write`, `Grep`, `Glob` | Full read/write access without command execution | +| Full access | All tools | Inherits all tools from parent (omit `tools` field) | + +## Troubleshooting + +### Claude not delegating to subagents + +If Claude completes tasks directly instead of delegating to your subagent: + +1. **Include the Agent tool**: subagents are invoked via the Agent tool, so it must be in `allowedTools` +2. **Use explicit prompting**: mention the subagent by name in your prompt (for example, "Use the code-reviewer agent to...") +3. **Write a clear description**: explain exactly when the subagent should be used so Claude can match tasks appropriately + +### Filesystem-based agents not loading + +Agents defined in `.claude/agents/` are loaded at startup only. If you create a new agent file while Claude Code is running, restart the session to load it. + +### Windows: long prompt failures + +On Windows, subagents with very long prompts may fail due to command line length limits (8191 chars). Keep prompts concise or use filesystem-based agents for complex instructions. + +## Related documentation + +* [Claude Code subagents](/en/sub-agents): comprehensive subagent documentation including filesystem-based definitions +* [SDK overview](/en/agent-sdk/overview): getting started with the Claude Agent SDK diff --git a/content/en/docs/claude-code/agent-sdk/todo-tracking.md b/content/en/docs/claude-code/agent-sdk/todo-tracking.md new file mode 100644 index 000000000..c500cb446 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/todo-tracking.md @@ -0,0 +1,189 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Todo Lists + +> Track and display todos using the Claude Agent SDK for organized task management + +Todo tracking provides a structured way to manage tasks and display progress to users. The Claude Agent SDK includes built-in todo functionality that helps organize complex workflows and keep users informed about task progression. + +### Todo Lifecycle + +Todos follow a predictable lifecycle: + +1. **Created** as `pending` when tasks are identified +2. **Activated** to `in_progress` when work begins +3. **Completed** when the task finishes successfully +4. **Removed** when all tasks in a group are completed + +### When Todos Are Used + +The SDK automatically creates todos for: + +* **Complex multi-step tasks** requiring 3 or more distinct actions +* **User-provided task lists** when multiple items are mentioned +* **Non-trivial operations** that benefit from progress tracking +* **Explicit requests** when users ask for todo organization + +## Examples + +### Monitoring Todo Changes + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Optimize my React app performance and track progress with todos", + options: { maxTurns: 15 } + })) { + // Todo updates are reflected in the message stream + if (message.type === "assistant") { + for (const block of message.message.content) { + if (block.type === "tool_use" && block.name === "TodoWrite") { + const todos = block.input.todos; + + console.log("Todo Status Update:"); + todos.forEach((todo, index) => { + const status = + todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌"; + console.log(`${index + 1}. ${status} ${todo.content}`); + }); + } + } + } + } + ``` + + ```python Python theme={null} + from claude_agent_sdk import query, AssistantMessage, ToolUseBlock + + async for message in query( + prompt="Optimize my React app performance and track progress with todos", + options={"max_turns": 15}, + ): + # Todo updates are reflected in the message stream + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, ToolUseBlock) and block.name == "TodoWrite": + todos = block.input["todos"] + + print("Todo Status Update:") + for i, todo in enumerate(todos): + status = ( + "✅" + if todo["status"] == "completed" + else "🔧" + if todo["status"] == "in_progress" + else "❌" + ) + print(f"{i + 1}. {status} {todo['content']}") + ``` + + +### Real-time Progress Display + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + class TodoTracker { + private todos: any[] = []; + + displayProgress() { + if (this.todos.length === 0) return; + + const completed = this.todos.filter((t) => t.status === "completed").length; + const inProgress = this.todos.filter((t) => t.status === "in_progress").length; + const total = this.todos.length; + + console.log(`\nProgress: ${completed}/${total} completed`); + console.log(`Currently working on: ${inProgress} task(s)\n`); + + this.todos.forEach((todo, index) => { + const icon = + todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌"; + const text = todo.status === "in_progress" ? todo.activeForm : todo.content; + console.log(`${index + 1}. ${icon} ${text}`); + }); + } + + async trackQuery(prompt: string) { + for await (const message of query({ + prompt, + options: { maxTurns: 20 } + })) { + if (message.type === "assistant") { + for (const block of message.message.content) { + if (block.type === "tool_use" && block.name === "TodoWrite") { + this.todos = block.input.todos; + this.displayProgress(); + } + } + } + } + } + } + + // Usage + const tracker = new TodoTracker(); + await tracker.trackQuery("Build a complete authentication system with todos"); + ``` + + ```python Python theme={null} + from claude_agent_sdk import query, AssistantMessage, ToolUseBlock + from typing import List, Dict + + + class TodoTracker: + def __init__(self): + self.todos: List[Dict] = [] + + def display_progress(self): + if not self.todos: + return + + completed = len([t for t in self.todos if t["status"] == "completed"]) + in_progress = len([t for t in self.todos if t["status"] == "in_progress"]) + total = len(self.todos) + + print(f"\nProgress: {completed}/{total} completed") + print(f"Currently working on: {in_progress} task(s)\n") + + for i, todo in enumerate(self.todos): + icon = ( + "✅" + if todo["status"] == "completed" + else "🔧" + if todo["status"] == "in_progress" + else "❌" + ) + text = ( + todo["activeForm"] + if todo["status"] == "in_progress" + else todo["content"] + ) + print(f"{i + 1}. {icon} {text}") + + async def track_query(self, prompt: str): + async for message in query(prompt=prompt, options={"max_turns": 20}): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, ToolUseBlock) and block.name == "TodoWrite": + self.todos = block.input["todos"] + self.display_progress() + + + # Usage + tracker = TodoTracker() + await tracker.track_query("Build a complete authentication system with todos") + ``` + + +## Related Documentation + +* [TypeScript SDK Reference](/en/agent-sdk/typescript) +* [Python SDK Reference](/en/agent-sdk/python) +* [Streaming vs Single Mode](/en/agent-sdk/streaming-vs-single-mode) +* [Custom Tools](/en/agent-sdk/custom-tools) diff --git a/content/en/docs/claude-code/agent-sdk/tool-search.md b/content/en/docs/claude-code/agent-sdk/tool-search.md new file mode 100644 index 000000000..f5d619030 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/tool-search.md @@ -0,0 +1,129 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Scale to many tools with tool search + +> Scale your agent to thousands of tools by discovering and loading only what's needed, on demand. + +Tool search enables your agent to work with hundreds or thousands of tools by dynamically discovering and loading them on demand. Instead of loading all tool definitions into the context window upfront, the agent searches your tool catalog and loads only the tools it needs. + +This approach solves two challenges as tool libraries scale: + +* **Context efficiency:** Tool definitions can consume large portions of the context window (50 tools can use 10-20K tokens), leaving less room for actual work. +* **Tool selection accuracy:** Tool selection accuracy degrades with more than 30-50 tools loaded at once. + +Tool search is enabled by default. This page covers [how it works](#how-tool-search-works), how to [configure it](#configure-tool-search), and how to [optimize tool discovery](#optimize-tool-discovery). + +## How tool search works + +When tool search is active, tool definitions are withheld from the context window. The agent receives a summary of available tools and searches for relevant ones when the task requires a capability not already loaded. The 3-5 most relevant tools are loaded into context, where they stay available for subsequent turns. If the conversation is long enough that the SDK compacts earlier messages to free space, previously discovered tools may be removed, and the agent searches again as needed. + +Tool search adds one extra round-trip the first time Claude discovers a tool (the search step), but for large tool sets this is offset by smaller context on every turn. With fewer than \~10 tools, loading everything upfront is typically faster. + +For details on the underlying API mechanism, see [Tool search in the API](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool). + + + Tool search requires Claude Sonnet 4 or later, or Claude Opus 4 or later. Haiku models do not support tool search. + + +## Configure tool search + +By default, tool search is always on. You can change this with the `ENABLE_TOOL_SEARCH` environment variable: + +| Value | Behavior | +| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| (unset) | Tool search is always on. Tool definitions are never loaded into context. This is the default. | +| `true` | Same as unset. | +| `auto` | Checks the combined token count of all tool definitions against the model's context window. If they exceed 10%, tool search activates. If they're under 10%, all tools are loaded into context normally. | +| `auto:N` | Same as `auto` with a custom percentage. `auto:5` activates when tool definitions exceed 5% of the context window. Lower values activate sooner. | +| `false` | Tool search is off. All tool definitions are loaded into context on every turn. | + +Tool search applies to all registered tools, whether they come from remote MCP servers or [custom SDK MCP servers](/en/agent-sdk/custom-tools). When using `auto`, the threshold is based on the combined size of all tool definitions across all servers. + +Set the value in the `env` option on `query()`. This example connects to a remote MCP server that exposes many tools, pre-approves all of them with a wildcard, and uses `auto:5` so tool search activates when their definitions exceed 5% of the context window: + + + ```typescript TypeScript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Find and run the appropriate database query", + options: { + mcpServers: { + "enterprise-tools": { + // Connect to a remote MCP server + type: "http", + url: "https://tools.example.com/mcp" + } + }, + allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server + env: { + ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context + } + } + })) { + if (message.type === "result" && message.subtype === "success") { + console.log(message.result); + } + } + ``` + + ```python Python theme={null} + import asyncio + from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + + + async def main(): + options = ClaudeAgentOptions( + mcp_servers={ + "enterprise-tools": { + "type": "http", + "url": "https://tools.example.com/mcp", + } + }, + allowed_tools=[ + "mcp__enterprise-tools__*" + ], # Wildcard pre-approves all tools from this server + env={ + "ENABLE_TOOL_SEARCH": "auto:5" # Activate tool search when tools exceed 5% of context + }, + ) + + async for message in query( + prompt="Find and run the appropriate database query", + options=options, + ): + if isinstance(message, ResultMessage) and message.subtype == "success": + print(message.result) + + + asyncio.run(main()) + ``` + + +Setting `ENABLE_TOOL_SEARCH` to `"false"` disables tool search and loads all tool definitions into context on every turn. This removes the search round-trip, which can be faster when the tool set is small (fewer than \~10 tools) and the definitions fit comfortably in the context window. + +## Optimize tool discovery + +The search mechanism matches queries against tool names and descriptions. Names like `search_slack_messages` surface for a wider range of requests than `query_slack`. Descriptions with specific keywords ("Search Slack messages by keyword, channel, or date range") match more queries than generic ones ("Query Slack"). + +You can also add a system prompt section listing available tool categories. This gives the agent context about what kinds of tools are available to search for: + +```text theme={null} +You can search for tools to interact with Slack, GitHub, and Jira. +``` + +## Limits + +* **Maximum tools:** 10,000 tools in your catalog +* **Search results:** Returns 3-5 most relevant tools per search +* **Model support:** Claude Sonnet 4 and later, Claude Opus 4 and later (no Haiku) + +## Related documentation + +* [Tool search in the API](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool): Full API documentation for tool search, including custom implementations +* [Connect MCP servers](/en/agent-sdk/mcp): Connect to external tools via MCP servers +* [Custom tools](/en/agent-sdk/custom-tools): Build your own tools with SDK MCP servers +* [TypeScript SDK reference](/en/agent-sdk/typescript): Full API reference +* [Python SDK reference](/en/agent-sdk/python): Full API reference diff --git a/content/en/docs/claude-code/agent-sdk/typescript-v2-preview.md b/content/en/docs/claude-code/agent-sdk/typescript-v2-preview.md new file mode 100644 index 000000000..554a9295f --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/typescript-v2-preview.md @@ -0,0 +1,392 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# TypeScript SDK V2 interface (preview) + +> Preview of the simplified V2 TypeScript Agent SDK, with session-based send/stream patterns for multi-turn conversations. + + + The V2 interface is an **unstable preview**. APIs may change based on feedback before becoming stable. Some features like session forking are only available in the [V1 SDK](/en/agent-sdk/typescript). + + +The V2 Claude Agent TypeScript SDK removes the need for async generators and yield coordination. This makes multi-turn conversations simpler, instead of managing generator state across turns, each turn is a separate `send()`/`stream()` cycle. The API surface reduces to three concepts: + +* `createSession()` / `resumeSession()`: Start or continue a conversation +* `session.send()`: Send a message +* `session.stream()`: Get the response + +## Installation + +The V2 interface is included in the existing SDK package: + +```bash theme={null} +npm install @anthropic-ai/claude-agent-sdk +``` + +## Quick start + +### One-shot prompt + +For simple single-turn queries where you don't need to maintain a session, use `unstable_v2_prompt()`. This example sends a math question and logs the answer: + +```typescript theme={null} +import { unstable_v2_prompt } from "@anthropic-ai/claude-agent-sdk"; + +const result = await unstable_v2_prompt("What is 2 + 2?", { + model: "claude-opus-4-6" +}); +if (result.subtype === "success") { + console.log(result.result); +} +``` + +
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    + See the same operation in V1 + + ```typescript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + const q = query({ + prompt: "What is 2 + 2?", + options: { model: "claude-opus-4-6" } + }); + + for await (const msg of q) { + if (msg.type === "result" && msg.subtype === "success") { + console.log(msg.result); + } + } + ``` +
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    + +### Basic session + +For interactions beyond a single prompt, create a session. V2 separates sending and streaming into distinct steps: + +* `send()` dispatches your message +* `stream()` streams back the response + +This explicit separation makes it easier to add logic between turns (like processing responses before sending follow-ups). + +The example below creates a session, sends "Hello!" to Claude, and prints the text response. It uses [`await using`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management) (TypeScript 5.2+) to automatically close the session when the block exits. You can also call `session.close()` manually. + +```typescript theme={null} +import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk"; + +await using session = unstable_v2_createSession({ + model: "claude-opus-4-6" +}); + +await session.send("Hello!"); +for await (const msg of session.stream()) { + // Filter for assistant messages to get human-readable output + if (msg.type === "assistant") { + const text = msg.message.content + .filter((block) => block.type === "text") + .map((block) => block.text) + .join(""); + console.log(text); + } +} +``` + +
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    + See the same operation in V1 + + In V1, both input and output flow through a single async generator. For a basic prompt this looks similar, but adding multi-turn logic requires restructuring to use an input generator. + + ```typescript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + const q = query({ + prompt: "Hello!", + options: { model: "claude-opus-4-6" } + }); + + for await (const msg of q) { + if (msg.type === "assistant") { + const text = msg.message.content + .filter((block) => block.type === "text") + .map((block) => block.text) + .join(""); + console.log(text); + } + } + ``` +
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    + +### Multi-turn conversation + +Sessions persist context across multiple exchanges. To continue a conversation, call `send()` again on the same session. Claude remembers the previous turns. + +This example asks a math question, then asks a follow-up that references the previous answer: + +```typescript theme={null} +import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk"; + +await using session = unstable_v2_createSession({ + model: "claude-opus-4-6" +}); + +// Turn 1 +await session.send("What is 5 + 3?"); +for await (const msg of session.stream()) { + // Filter for assistant messages to get human-readable output + if (msg.type === "assistant") { + const text = msg.message.content + .filter((block) => block.type === "text") + .map((block) => block.text) + .join(""); + console.log(text); + } +} + +// Turn 2 +await session.send("Multiply that by 2"); +for await (const msg of session.stream()) { + if (msg.type === "assistant") { + const text = msg.message.content + .filter((block) => block.type === "text") + .map((block) => block.text) + .join(""); + console.log(text); + } +} +``` + +
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    + See the same operation in V1 + + ```typescript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Must create an async iterable to feed messages + async function* createInputStream() { + yield { + type: "user", + session_id: "", + message: { role: "user", content: [{ type: "text", text: "What is 5 + 3?" }] }, + parent_tool_use_id: null + }; + // Must coordinate when to yield next message + yield { + type: "user", + session_id: "", + message: { role: "user", content: [{ type: "text", text: "Multiply by 2" }] }, + parent_tool_use_id: null + }; + } + + const q = query({ + prompt: createInputStream(), + options: { model: "claude-opus-4-6" } + }); + + for await (const msg of q) { + if (msg.type === "assistant") { + const text = msg.message.content + .filter((block) => block.type === "text") + .map((block) => block.text) + .join(""); + console.log(text); + } + } + ``` +
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    + +### Session resume + +If you have a session ID from a previous interaction, you can resume it later. This is useful for long-running workflows or when you need to persist conversations across application restarts. + +This example creates a session, stores its ID, closes it, then resumes the conversation: + +```typescript theme={null} +import { + unstable_v2_createSession, + unstable_v2_resumeSession, + type SDKMessage +} from "@anthropic-ai/claude-agent-sdk"; + +// Helper to extract text from assistant messages +function getAssistantText(msg: SDKMessage): string | null { + if (msg.type !== "assistant") return null; + return msg.message.content + .filter((block) => block.type === "text") + .map((block) => block.text) + .join(""); +} + +// Create initial session and have a conversation +const session = unstable_v2_createSession({ + model: "claude-opus-4-6" +}); + +await session.send("Remember this number: 42"); + +// Get the session ID from any received message +let sessionId: string | undefined; +for await (const msg of session.stream()) { + sessionId = msg.session_id; + const text = getAssistantText(msg); + if (text) console.log("Initial response:", text); +} + +console.log("Session ID:", sessionId); +session.close(); + +// Later: resume the session using the stored ID +await using resumedSession = unstable_v2_resumeSession(sessionId!, { + model: "claude-opus-4-6" +}); + +await resumedSession.send("What number did I ask you to remember?"); +for await (const msg of resumedSession.stream()) { + const text = getAssistantText(msg); + if (text) console.log("Resumed response:", text); +} +``` + +
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    + See the same operation in V1 + + ```typescript theme={null} + import { query } from "@anthropic-ai/claude-agent-sdk"; + + // Create initial session + const initialQuery = query({ + prompt: "Remember this number: 42", + options: { model: "claude-opus-4-6" } + }); + + // Get session ID from any message + let sessionId: string | undefined; + for await (const msg of initialQuery) { + sessionId = msg.session_id; + if (msg.type === "assistant") { + const text = msg.message.content + .filter((block) => block.type === "text") + .map((block) => block.text) + .join(""); + console.log("Initial response:", text); + } + } + + console.log("Session ID:", sessionId); + + // Later: resume the session + const resumedQuery = query({ + prompt: "What number did I ask you to remember?", + options: { + model: "claude-opus-4-6", + resume: sessionId + } + }); + + for await (const msg of resumedQuery) { + if (msg.type === "assistant") { + const text = msg.message.content + .filter((block) => block.type === "text") + .map((block) => block.text) + .join(""); + console.log("Resumed response:", text); + } + } + ``` +
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    + +### Cleanup + +Sessions can be closed manually or automatically using [`await using`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management), a TypeScript 5.2+ feature for automatic resource cleanup. If you're using an older TypeScript version or encounter compatibility issues, use manual cleanup instead. + +**Automatic cleanup (TypeScript 5.2+):** + +```typescript theme={null} +import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk"; + +await using session = unstable_v2_createSession({ + model: "claude-opus-4-6" +}); +// Session closes automatically when the block exits +``` + +**Manual cleanup:** + +```typescript theme={null} +import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk"; + +const session = unstable_v2_createSession({ + model: "claude-opus-4-6" +}); +// ... use the session ... +session.close(); +``` + +## API reference + +### `unstable_v2_createSession()` + +Creates a new session for multi-turn conversations. + +```typescript theme={null} +function unstable_v2_createSession(options: { + model: string; + // Additional options supported +}): SDKSession; +``` + +### `unstable_v2_resumeSession()` + +Resumes an existing session by ID. + +```typescript theme={null} +function unstable_v2_resumeSession( + sessionId: string, + options: { + model: string; + // Additional options supported + } +): SDKSession; +``` + +### `unstable_v2_prompt()` + +One-shot convenience function for single-turn queries. + +```typescript theme={null} +function unstable_v2_prompt( + prompt: string, + options: { + model: string; + // Additional options supported + } +): Promise; +``` + +### SDKSession interface + +```typescript theme={null} +interface SDKSession { + readonly sessionId: string; + send(message: string | SDKUserMessage): Promise; + stream(): AsyncGenerator; + close(): void; +} +``` + +## Feature availability + +Not all V1 features are available in V2 yet. The following require using the [V1 SDK](/en/agent-sdk/typescript): + +* Session forking (`forkSession` option) +* Some advanced streaming input patterns + +## Feedback + +Share your feedback on the V2 interface before it becomes stable. Report issues and suggestions through [GitHub Issues](https://github.com/anthropics/claude-code/issues). + +## See also + +* [TypeScript SDK reference (V1)](/en/agent-sdk/typescript) - Full V1 SDK documentation +* [SDK overview](/en/agent-sdk/overview) - General SDK concepts +* [V2 examples on GitHub](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/hello-world-v2) - Working code examples diff --git a/content/en/docs/claude-code/agent-sdk/typescript.md b/content/en/docs/claude-code/agent-sdk/typescript.md new file mode 100644 index 000000000..8505e2945 --- /dev/null +++ b/content/en/docs/claude-code/agent-sdk/typescript.md @@ -0,0 +1,2786 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# Agent SDK reference - TypeScript + +> Complete API reference for the TypeScript Agent SDK, including all functions, types, and interfaces. + +